guaguastandup/zotero-pdf2zh · 上手攻略

  • 仓库：guaguastandup/zotero-pdf2zh
  • 链接：https://github.com/guaguastandup/zotero-pdf2zh
  • 分类：academic-writing
  • 作者：Jay
  • 更新：2026-07-14

这是什么

zotero-pdf2zh 是一款 Zotero 插件，配合本地 Python 翻译服务，可将学术 PDF 论文翻译成中文，同时保留数学公式、表格、参考文献等复杂内容的排版。它基于 PDFMathTranslate/Byaidu 和 PDFMathTranslate-next 两款开源翻译内核构建，支持双语对照（原文+译文左右分栏）或纯译文输出，是阅读英文文献的效率神器。

本质上是 Zotero 内的嵌入式 PDF 翻译工作流：用户无需手动复制文字、上传翻译网站、下载译文，只需右键点击 PDF 条目，插件自动完成提取→翻译→生成双语 PDF 的全流程。

解决什么问题

学术人员阅读英文 PDF 时面临的核心痛点：

  • 机器翻译破坏公式：Google Translate 直接翻译 PDF 时，LaTeX 公式、数学符号全部乱码
  • 来回切换费时：复制文字→粘贴到翻译工具→回填译文，流程碎片化
  • 双语对照难：只想看某一段的翻译时，无法同时看到原文和译文
  • Zotero 生态缺失：Zotero 是最主流的学术文献管理工具，但一直没有好用的内置翻译方案

快速安装

环境要求

  • Python 3.12（建议）
  • Zotero 7 或 Zotero 8（Beta）
  • uv（推荐）或 conda 环境管理工具

第一步：安装 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

第二步：下载并解压服务文件

mkdir zotero-pdf2zh && cd zotero-pdf2zh
wget https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/refs/heads/main/server.zip
unzip server.zip
cd server

⚠️ Windows 用户注意：请勿在 C 盘创建项目文件夹，建议在 D 盘操作。

第三步：启动翻译服务

# uv 用户（推荐，最简单）
uv run --python 3.12 --with-requirements requirements.txt server.py

# conda 用户
conda create -n zotero-pdf2zh-server python=3.12 -y
conda activate zotero-pdf2zh-server
pip install -r requirements.txt
python server.py --env_tool=conda

服务启动后访问 http://127.0.0.1:8890 可查看翻译进度页面。翻译时不要关闭此终端窗口。

第四步：安装 Zotero 插件

下载最新 XPI：https://github.com/guaguastandup/zotero-pdf2zh/releases

在 Zotero 中打开「工具 → 插件」，将 .xpi 文件拖入安装。

第五步：插件配置

在 Zotero 插件设置页面填写： - Python Server IP：http://127.0.0.1:8890 - 点击「检查连接」确认服务正常 - 选择翻译引擎（推荐 PDF2ZH Next，新版维护更活跃）

核心用法

基本翻译操作

在 Zotero 中对条目或 PDF 附件右键，选择：

选项 说明
翻译PDF 生成纯译文 PDF（默认生成文件）
双语对照 生成左原文右译文的对照 PDF
裁剪PDF 双栏论文先裁剪再拼接，适合手机阅读
双语对照(裁剪) 先裁剪为单栏，再左右拼接双语

支持多选条目批量翻译，右键批量操作。

常用启动参数

# 指定端口（默认 8890）
python server.py --port=9999

# 使用 pip 镜像加速（国内推荐）
python server.py --enable_mirror=True --mirror_source=https://mirrors.ustc.edu.cn/pypi/simple

# 启动时禁用自动检查更新
python server.py --check_update=False

翻译引擎对比

对比项 PDF2ZH（旧版） PDF2ZH Next（新）
维护状态 ❌ 停止维护 ✅ 活跃维护
表格翻译 ❌ 不支持 ✅ 支持
术语表 ❌ 不支持 ✅ 自动提取术语
OCR 兼容 ❌ 不支持 ✅ 支持
双语模式默认 Top & Bottom Left & Right
推荐程度 不推荐 推荐

⚠️ PDF2ZH Next 是当前推荐引擎，旧版 PDF2ZH 已停止维护，不建议使用。

典型适用场景

  1. 阅读英文 PDF 论文：直接生成双语对照，边看原文边看翻译，快速理解复杂论文
  2. 翻译数学/理工科文献：LaTeX 公式、积分符号等能正确保留，不会出现乱码
  3. 批量翻译多篇文献：选中文献条目批量翻译，适合文献调研阶段
  4. 制作翻译参考资料：生成的双语 PDF 可直接作为精读笔记存档
  5. OCR 扫描版 PDF 翻译：新版引擎支持 OCR 识别扫描件（需配置 OCR 功能）

坑与注意

  1. server.py 必须保持运行：每次翻译都需要翻译服务在后台运行，关闭终端后翻译功能不可用。建议创建桌面快捷脚本（Windows .bat 或 macOS/Linux alias）方便一键启动。
  2. 首次启动下载资源慢：PDF2ZH Next 首次运行需要下载字体和模型文件，可能卡在某个进度很久。国内用户建议加入 QQ 群下载离线资源包，或预先下载 exe 版本进行缓存。
  3. Windows exe 模式：不想配置 Python 环境的 Windows 用户，可下载 PDFMathTranslate-next 提供的预编译 exe，参考仓库文档中的「Windows exe 版本安装」章节。使用 exe 模式时启动命令： bash python server.py --enable_winexe=True --winexe_path='./pdf2zh-v2.x.x-BabelDOC-v0.x.x-win64/pdf2zh/pdf2zh.exe'
  4. API Key 配置：PDF2ZH Next 版的翻译服务中，硅基流动（siliconflowfree）提供免费额度，DeepSeek 翻译效果较好且有缓存机制。配置方式参考仓库 README 中的「翻译服务介绍」表格。
  5. 目录嵌套问题：unzip 解压 server.zip 后可能出现 server/server/ 双层嵌套，需要手动整理（参考 README 中的说明）。
  6. Zotero 插件版本：当前版本 v4.0.1（截至 2026-07），Zotero 7 和 Zotero 8 均可使用，但 Zotero 8 适配由社区贡献者维护，可能存在偶发兼容问题。

与同类对比

工具 优点 缺点
zotero-pdf2zh 集成 Zotero，公式保留好，双语对照 需要本地配置 Python 环境
知云文献翻译 界面简单，有客户端 公式保留差，双语对照需付费
DeepL/Google 翻译 通用性强 无法保留公式排版，需手动操作
PDFMathTranslate（命令行） 开源本地部署 无 Zotero 集成，操作繁琐

核心差异：zotero-pdf2zh 是目前唯一深度集成 Zotero生态、支持公式保留且提供双语对照的专业 PDF 翻译方案，非常适合学术文献管理场景。

一句话推荐结论

读英文论文还在来回复制翻译？zotero-pdf2zh 让你在 Zotero 里一键生成保留公式的双语 PDF，文献阅读效率直接翻倍。

本攻略基于 2026-07-14 公开信息整理。插件版本 v4.0.1，server 版本 v4.0.4，安装过程建议严格按 README 步骤操作。