Zotero PDF2zh 能在 Zotero 中直接翻译 PDF 论文的插件

🧭 核心功能与工作模式

Zotero PDF2zh 将 PDF 翻译工具（PDF2zh / PDF2zh Next）集成进 Zotero 的工作流，让你能直接在文献库中处理论文。

核心工作流程：

• 本地服务 + Zotero 插件：项目由一个本地运行的 Python 翻译服务（Server） 和一个 Zotero 插件（Add-on） 组成。翻译时，Zotero 插件将 PDF 发送给本地服务，服务完成翻译后返回结果。
• 两种翻译引擎：
  • PDF2zh (旧版)：速度较快，支持自定义字体，但已不再活跃维护。
  • PDF2zh Next (新版，推荐)：持续更新，支持术语表、表格翻译、OCR兼容模式等功能。
• 灵活的翻译选项：支持生成标准双语对照、裁剪版（适合移动端阅读）、左右分栏对比等多种输出格式，并支持多选批量翻译。

📦 部署与安装（完整步骤）

本项目需要同时部署 Python 服务端和 Zotero 插件。请按顺序操作。

第零步：环境准备

• 安装 Python：建议安装 Python 3.12 版本。在命令行中输入 python --version 确认。
• 安装 Zotero：支持 Zotero 7/8/9/10。
• 打开命令行（终端）：后续所有命令都在此执行。
  • Windows：按 Win+R，输入 cmd，建议以管理员身份运行。
  • macOS：按 Cmd+空格，输入“终端”。
  • Linux：Ctrl+Alt+T。

第一步：安装环境管理工具（推荐 uv）

选择一个工具来管理 Python 依赖。如果不确定，选 uv（更快、更现代）。

# macOS/Linux
wget -qO- https://astral.sh/uv/install.sh | sh

# Windows (在 PowerShell 中执行)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装后，执行 uv --version 验证成功。

第二步：下载服务端文件

1. 创建项目目录（Windows用户请勿在C盘操作，建议在D盘）：

   mkdir zotero-pdf2zh && cd zotero-pdf2zh

2. 下载并解压服务端：

   # 从 GitHub 下载
   wget https://github.com/guaguastandup/zotero-pdf2zh/releases/latest/download/server.zip
   unzip server.zip
   cd server

   网络问题：GitHub 下载失败时，可将 URL 中的 github.com 替换为 gitee.com，并确保下载的是 server.zip 而非源码归档。

3. 检查目录结构：确认当前路径下有一个 server.py 文件。如果看到 server/server/ 嵌套，说明解压有误，需手动调整。

第三步：启动翻译服务

uv 用户（推荐） 在 server 目录下执行：

uv run --python 3.12 --with-requirements requirements.txt server.py

重要：翻译功能依赖此脚本运行，使用翻译时不要关闭此终端窗口。

第四步：安装 Zotero 插件

1. 从 GitHub Releases 下载最新 .xpi 插件文件。
2. 打开 Zotero，点击“工具”→“插件”，将 .xpi 文件拖入插件窗口，按提示安装。
3. （可选）安装后重启 Zotero 确保生效。

第五步：配置 Zotero 插件

1. 在 Zotero 插件设置页面，找到 “Python Server IP” 输入框，确保地址为 http://127.0.0.1，端口为 8890（与上一步服务启动的默认端口一致）。

2. 点击旁边的 “检查连接” 按钮，应显示“连接成功”。

3. 配置翻译服务（关键）：

   • 免费快速体验：在“翻译服务”下拉菜单中，选择 siliconflowfree（基于硅基流动的 GLM 模型，仅支持 pdf2zh_next 引擎）。

   • 使用自己的 API：

     1. 在“LLM API配置管理”中，点击“新增”，填写你的服务商信息（如 DeepSeek、OpenAI 的 URL、API Key 和模型名）。
     2. 在页面顶部的“翻译服务”下拉菜单中，选择你刚配置好的服务名称。

     注意：仅添加配置而不选择服务，翻译功能无法使用。

🚀 日常使用与翻译

1. 确保终端中的服务脚本始终保持运行。
2. 在 Zotero 中，选中一个或多个 PDF 条目。
3. 右键点击，在 “PDF2zh” 子菜单中选择翻译方式：
   • 翻译 PDF：生成默认的双语对照文件。
   • 裁剪 PDF：将双栏论文裁剪为适合手机阅读的单栏格式。
   • 双语对照：生成原文与译文左右/上下对照的版本。
   • 双语对照(裁剪)：针对双栏论文，先裁剪再拼接。
4. 翻译任务会发送到终端执行，你可以在终端看到进度，也可在浏览器访问 http://127.0.0.1:8890 查看网页版进度和记录。

⚙️ 高级配置与维护

• 更新 Python 环境：当插件提示或需要新功能时，在 server 目录运行 python update_packages.py 更新翻译依赖。
• 修改端口：如果 8890 端口冲突，启动服务时添加参数，如 ... server.py --port=9999，并同步修改 Zotero 插件设置中的端口。
• 一键启动：为避免每次手动输入命令，可创建桌面快捷方式（Windows .bat 文件）或终端别名（macOS/Linux alias），具体方法见文档。
• Docker 部署：项目社区也提供了 Docker 镜像，适合喜欢容器化部署的用户。

❓ 常见问题排查

问题	解决方案
插件提示“NetworkError”	首先点击插件设置中的“检查连接”。若失败，检查：终端服务是否运行；端口是否被占用或修改后未同步；关闭防火墙/杀毒软件。
首次翻译卡住不动	pdf2zh_next 首次运行需下载字体/模型（约几百MB），较慢。可尝试下载其 exe 包 并运行一次以提前缓存资源。
翻译后部分段落缺失	程序会以原文替代翻译失败的段落。可尝试：更换翻译引擎；检查 API 是否超限或欠费（查看终端报错）；在 LLM 额外参数中开启对应服务的 *_enable_json_mode（如 deepseek_enable_json_mode）尝试改善。
扫描版 PDF 无法翻译	插件不提供 OCR。需先用 Adobe Acrobat 等外部工具对扫描件进行 OCR 文字识别，再翻译。

总结

Zotero PDF2zh 通过本地服务+插件的模式，为学术文献翻译提供了强大的解决方案。部署的核心是正确配置 Python 环境和 API 服务。对于新手，建议按顺序：安装 uv → 下载并启动服务端 → 安装 Zotero 插件并配置免费 siliconflowfree 服务进行测试。熟悉流程后，再切换至更稳定的付费 API。使用前请务必阅读常见问题（FAQ），其中包含了绝大多数运行中可能遇到的问题及解决方案。