缘由

最近，PDFMathTranslate推出了适配Zotero的插件，我经过一番摸索，已经可以正常使用了，这里特地整理分享给大家，方便使用。

项目地址：Zotero PDF中文翻译插件

使用步骤

一、安装或更新pdf2zh

首次安装请使用：

pip install pdf2zh

如果已安装，则执行下面命令更新到最新版：

pip install -U pdf2zh

第二步：下载并安装Zotero插件

在 Zotero 中文社区搜索「pdf2zh」，或直接前往插件发布页 zotero-pdf2zh，下载以.xpi结尾的插件文件，亦或是Zotero插件“插件市场”里面安装。

下载完成后：

打开Zotero，依次点击 工具 → 插件；
将下载的.xpi插件文件直接拖入插件窗口即可自动安装。

第三步：配置脚本及相关文件

添加配置文件

1. 新建并配置 `config.json` 文件

在电脑任意位置新建一个名为 config.json 的文件，并填入以下模板：

{
    "USE_MODELSCOPE": "0",
    "NOTO_FONT_PATH": "/app/SourceHanSerifCN-Regular.ttf",
    "translators": [
        {
            "name": "deeplx",
            "envs": {
                "DEEPLX_ENDPOINT": "http://localhost:1188/translate/",
                "DEEPLX_ACCESS_TOKEN": null
            }
        },
        {
            "name": "ollama",
            "envs": {
                "OLLAMA_HOST": "http://127.0.0.1:11434",
                "OLLAMA_MODEL": "gemma2"
            }
        }
    ]
}

字体路径（NOTO_FONT_PATH）建议使用绝对路径。
具体设置可参考：example config.json
如果不确定具体如何填写配置，可以通过GUI界面查看。方法如下：
- 命令行运行：
```
 pdf2zh -i
```
- 在弹出的GUI界面选择对应的翻译服务，如OpenAI。将Option栏内的信息（如 OPENAI_BASE_URL 等）复制填写到config.json中即可。

Windows系统查看字体路径方法：
打开文件夹C:\Windows\Fonts 或按 Win + i 搜索「字体」→ 打开「字体设置」→「旧字体控制面板界面」，找到对应字体后，右键→「属性」→「安全」，复制「对象名称」即为字体路径。
注意：路径中的\应替换为/或\\。

2. 新建并配置 `server.py` 文件

复制 server.py 的全部代码，新建文件命名为 server.py 并粘贴进去。

需要修改的是脚本中的默认配置：

# 设置翻译后文件的输出路径（临时路径，用完可删）
translated_dir = "./translated/"  

# 设置配置文件 config.json 的路径
config_path = './config.json'

建议使用绝对路径，例如：(ctrl + shift +c复制路径)

translated_dir = "D:/python_project/python1/zotero-pdf2zh/translated/pdf2zh"
config_path = "D:/python_project/python1/zotero-pdf2zh/config.json"

3. Zotero插件内配置

打开Zotero，进入 编辑 → 设置 → pdf2zh：

「翻译配置」内容需与 server.py 文件中的路径一致。
如果更换翻译服务，先在config.json中确认配置无误后再调整此处配置。
「重命名条目为短标题」建议勾选，以防止因文件路径过长导致翻译失败。
「默认生成文件」选项根据个人需求勾选。

如何使用插件翻译PDF

首先运行 server.py 脚本：
```
python server.py
```
然后在Zotero中找到需要翻译的文献PDF，右键点击：
选择 PDF2zh：Translate PDF，即可开始翻译；
默认生成两个文件：
- dual：一页原文、一页译文交替；
- mono：纯翻译版本。

插件提供了另外两个有用的功能：

PDF2zh：Cut PDF
- 将双栏PDF剪切为单栏，更适合手机等移动设备阅读。
- 生成的单栏PDF文件名含有cut标识。
PDF2zh：中英双栏对照
- 将翻译后的dual文件加工成中文和英文双栏对照的形式。
- 生成的文件名含有compare标识。

常见错误处理

若遇到服务器响应失败，通常是因为配置文件 (config.json) 或脚本 (server.py) 填写错误造成的。
请仔细检查以下内容：

Python 与依赖环境
- 使用 Python 3.10–3.12 版本
- 确保已正确安装 pdf2zh、flask、pypdf、pdfminer.six==20250416 等依赖
工具版本匹配
- 推荐使用 pdf2zh v1.9.6
- zotero-pdf2zh 插件建议使用 v2.4.1 或以上版本
路径规范且存在
- 字体路径正确且存在
- 所有路径建议使用绝对路径
- 避免路径中出现中文、空格、或特殊字符
- 路径中的 \ 应统一替换为 / 或 \\
配置文件设置
- config.json 应位于 server.py 同级目录，或通过参数传入完整路径
- JSON 格式必须合法，注意标点（引号、逗号）闭合
- translators 字段中应包含你启用的翻译服务，并提供完整凭证
Python 脚本执行
- server.py 启动端口应与 Zotero 插件设置一致
- 启动脚本前建议先 cd 至脚本所在目录
- 若修改端口，请同时更新插件中的端口配置
Zotero 插件设置
- 插件中的翻译参数需与 config.json 和脚本配置对应
- 输出路径建议保持简洁，并避免超过操作系统路径长度限制
翻译服务建议与回退策略
- 优先使用 Bing 或 Google 翻译服务，设置更简单、响应更快
- 若翻译失败，建议先切换 Bing 验证配置文件，再尝试 Deepseek、硅基流动等其他服务
端口与依赖冲突处理
- 如端口被占用，可尝试修改 server.py 中的默认端口
- 遇到依赖错误，请根据官方推荐版本重新安装对应库