在 Zotero 中直接使用 PDF2zh 与 PDF2zh_next 翻译 PDF,保留公式与排版,并提供双语对照、裁剪阅读、批量翻译与多种 LLM 服务配置。
📚 项目文档: zotero-pdf2zh.github.io
📝 其他语言 / Other Languages:
English | 日本語 | 한국어 | Italiano | Français
Note: The translations above were generated by AI and may contain inaccuracies. For the most accurate information, please refer to this document.
🚀 v4.1.7:远程/Docker 翻译完成后优先 HTTP 挂附件;新旧插件协议兼容;进度条显示翻译百分比;加固附件文件名;补齐 pdf2zh_next 额外字段(含
*_enable_json_mode),LLM 编辑器可从下拉列表添加,默认不开启 JSON mode。请同时更新插件和 Server。🚀 v4.1.6:翻译改为后台任务,避免 Windows 长连接 Network Error;进度查询不再打断终端进度条。
🚀 v4.1.5:修复 Windows 翻译中途 Network Error;进度查询不再打断终端进度条。请同时更新插件和 Server。
🚀 v4.1.4:翻译完成后优先从本机挂附件;终端进度条按窗口宽度绘制。
🚀 v4.1.2:支持 GitHub / Gitee 双源更新和启动通知;DeepSeek V4 默认不思考。
🚀 v4.1.1:修复 Windows Conda 路径、环境误判,以及控制台日志崩溃。
🚀 v4.1.0:支持 DeepSeek V4;自动识别 uv/conda 并在当前环境更新;完善 Dual / Crop 相关处理。
📢 重要通知(2026年8月19日): 本插件正在进行全面重构,预期九月份发布新版本,暂时不会在群里及时解答目前版本相关的问题,请自行向AI提问或阅读本文档~也请开发者暂时不要对本仓库提交贡献,因为无法和新版本进行合并。
📦 下载最新版本: Zotero 插件 XPI · Server · 完整文档
本指南将引导您完成 Zotero PDF2zh 插件的安装和配置。
❓ 遇到问题
pdf2zh_next < 2.9.0,首次启动本版本会询问是否更新;已经 >=2.9.0 则跳过。DeepSeek V4 默认不思考,旧环境可以继续翻译;只有手动开启思考才需要 2.9.0。
N、更新失败,或希望主动维护环境,可在 server 目录运行 python update_packages.py。该命令会沿用已有 uv/conda;没有现有环境时优先 uv。Python:下载链接,建议安装 3.12 版本
Zotero:支持 Zotero 7、Zotero 8、Zotero 9和Zotero 10,如无意外插件会持续支持最新版本,如果Zotero内自动更新失败,请下载最新插件文件重新安装尝试。
打开命令行工具(后续步骤都在命令行中执行):
Win + R → 输入 cmd → 回车(建议以管理员身份运行)Cmd + 空格 → 输入"终端" → 回车Ctrl + Alt + T选择一个环境管理工具。如果不确定选哪个,推荐 uv。
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,能看到版本号即成功。
如果提示找不到命令,需将 uv 路径添加到环境变量并重启终端:
# MacOS/Linux
export PATH="$HOME/.local/bin:$PATH"
# Windows PowerShell
$env:Path = "$env:USERPROFILE\.local\bin;$env:Path"
conda安装
参考 Miniconda 安装指南进行安装,安装后执行 conda --version 验证。
⚠️ Windows用户注意:请勿在C盘(系统盘)下创建项目文件夹,建议在D盘或其他非系统盘操作。例如:先执行
D:切换到D盘,再执行后续命令。
# 1. 创建并进入zotero-pdf2zh文件夹
mkdir zotero-pdf2zh && cd zotero-pdf2zh
# 2. 下载并解压server文件夹
# GitHub 下载失败时,可改用 Gitee: https://gitee.com/guaguastandup/zotero-pdf2zh/raw/v4.1.7/server.zip
# 不要下载 Gitee 源码归档 repository/archive/*.zip(经常是 HTML 登录/验证页)
wget https://github.com/guaguastandup/zotero-pdf2zh/releases/latest/download/server.zip
unzip server.zip
# 3. 进入server文件夹
cd server
💡 提示:确认目录结构
解压后,请确认您的目录结构应该是:
zotero-pdf2zh/ └── server/ ├── server.py ├── ... └── requirements.txt如果您看到的是
server/server/这样的嵌套结构(两层 server),说明解压出现了嵌套问题,请执行:# 回到上级目录 cd .. # 移动内容到正确位置 mv server/server/* server/ # 删除空的嵌套目录 rmdir server/server # 重新进入 server 目录 cd server
快速检查方法:
执行 cd server 后,运行 ls server.py,如果能看到 server.py 文件,说明目录结构正确。如果提示找不到文件,说明存在嵌套问题。
uv 用户(推荐)
uv run --python 3.12 --with-requirements requirements.txt server.py
conda 用户
# 1. 创建环境(仅首次需要)
conda create -n zotero-pdf2zh-server python=3.12 -y
# 2. 激活环境
conda activate zotero-pdf2zh-server
# 3. 安装依赖(仅首次需要)
pip install -r requirements.txt
# 4. 启动服务
python server.py --env_tool=conda
⚠️ 重要:翻译功能依赖本脚本运行,使用翻译时不要关闭此终端窗口。
在启动命令后面追加参数即可,例如 ... server.py --port=9999:
| 参数 | 说明 | 默认值 |
|---|---|---|
--host | Server 监听地址;默认仅本机访问,远程部署时才使用 0.0.0.0 | 127.0.0.1 |
--port | 服务端口号 | 8890 |
--check_update | 启动时检查更新 | True |
--update_source | 优先更新源(github / gitee)。会两个都试,失败自动换另一个 | gitee |
--enable_mirror | 启用 pip 镜像加速 | True |
--mirror_source | 自定义镜像源 URL | https://mirrors.ustc.edu.cn/pypi/simple |
--enable_winexe | 使用 Windows exe 模式(需配合 --winexe_path) | False |
server 文件夹(会影响环境路径)。server 文件夹。新版 Server/update_packages.py 会自动沿用已有 conda 环境;新安装仍优先 uv。127.0.0.1。确实需要其他设备访问时显式添加 --host 0.0.0.0,并自行配置防火墙/可信网络。最新版本 v4.1.7 下载链接

检查服务器连接
在插件设置页面中,点击"Python Server IP"输入框旁边的"检查连接"按钮,可测试与Python服务的连接状态。若显示连接成功,则服务正常运行;若显示连接失败,请检查:
配置选项说明
切换翻译引擎pdf2zh/pdf2zh_next,界面将显示不同引擎的翻译配置
其他说明(初次配置可以忽略)
关于qps(Query Per Second)和poolsize选项:
具体数值请参考您的LLM服务商提供的参数(例如zhipu)
- 计算公式:
qps = rpm / 60(RPM = Request Per Minute)- 对于上游为qps/rpm限速:pool size = qps * 10;
- 对于上游为并发数限制: pool size = max(向下取整(0.9*官方并发数限制), 官方并发数限制-20),qps = pool size
- 如果您不知道怎么设置, 请直接设置qps即可, pool size设置为默认值0即可
翻译引擎pdf2zh的自定义字体:
- 字体文件路径为本地路径。
- 如果采用远端服务器部署,暂时无法在插件设置中指定字体路径。需要您手动修改
config.json文件中的NOTO_FONT_PATH字段。
额外配置参数名需要与 config 文件中的字段相同。v4.1.7 起,在「LLM API配置管理」里点「添加参数」,可从当前服务支持的字段下拉选择(也可选「自定义」手填)。OpenAI / DeepSeek / SiliconFlow 等支持 *_enable_json_mode(如 openai_enable_json_mode、deepseek_enable_json_mode),默认关闭;部分模型漏译段落时可尝试设为 true。字段说明见 额外参数文档 与 extraData.md
网页端查看翻译进度
服务启动后,可在浏览器中访问 http://127.0.0.1:8890 查看翻译进度和使用相关功能:



功能说明:
📢: v4.0.3(3月7日) windows端暂时不支持多进度条显示(多个pdf同时翻译时只会有一个进度条会更新,是bug待修复)
翻译引擎对比
插件支持两种翻译引擎,请根据需求选择:
| 对比项 | PDF2ZH (旧版) | PDF2ZH Next (新版) |
|---|---|---|
| 维护状态 | ❌ 不再活跃维护 | ✅ 持续更新维护 |
| 翻译速度 | ⚡ 较快 | 速度适中 |
| 自定义字体 | ✅ 支持更换自定义字体 | ❌ 不支持 |
| 配置文件 | config.json | config.toml |
| 双语模式 | 默认为Top&Bottom | 默认为 Left&Right |
| 术语表功能 | ❌ 不支持 | ✅ 自动提取并使用术语表 |
| 表格翻译 | ❌ 不支持 | ✅ 支持表格内容翻译 |
| OCR兼容 | ❌ 不支持 | ✅ 支持 OCR 兼容模式和自动 OCR |
| 支持的翻译服务 | 支持海量翻译服务 | 提供免费 siliconflowfree |
| 上游项目 | Byaidu/PDFMathTranslate | PDFMathTranslate-next |
翻译服务配置
配置翻译服务需完成两步:
第一步:添加API配置
在"LLM API配置管理"区域点击"新增",填写服务配置信息。同一服务可添加多个配置,但只能激活其中一个。
第二步:选择翻译服务
在页面顶部的"翻译服务"下拉菜单中,选择要使用的服务名称。
警告:仅添加API配置不会生效,必须完成第二步选择服务,翻译功能才能使用。
💡 翻译服务介绍(必读)
| 服务类型 | 服务名称 | 服务介绍 | 💡注意事项 |
|---|---|---|---|
| 免费&免配置的翻译服务 | siliconflowfree | 基于硅基流动提供的GLM4-9B模型, 仅支持翻译引擎pdf2zh_next,由@硅基流动、@pdf2zh_next 和 @BabelDOC联合提供服务 | 1. 此服务无需选择qps,默认为20 2.此服务可能会存在漏翻译的情况,如果需要高质量翻译请优先选择其他服务 3. 此服务仅支持pdf2zh_next引擎 |
| 免费&免配置的翻译服务 | bing/google | bing/google的官方机器翻译 | bing和goole的翻译服务都存在限流,如果翻译失败,请将并发数设置调至2及以下重试 |
| 具有优惠/赠送的翻译服务 | openaliked | 加入火山引擎协作计划,个人用户每个模型每天最多赠送50w token | 1. 协作计划的额度赠送规则是:按照前一天参加协作的token量等额计算(例如您昨天使用了10w token,那么今天的赠送额度则为10w token)上限为50w,请注意检查自己的额度使用情况,避免超额 2. 此服务支持高并发数:可设置并发数为500~1000 |
| 具有优惠/赠送的翻译服务 | silicon | 通过邀请好友可以获得14元赠送金额 | 1. 此服务url需填写为: https://api.siliconflow.cn/v1,如果后面有completions等后缀,请删除。2. 此服务免费版支持的线程数较低,建议设置为6左右 |
| 具有优惠/赠送的翻译服务 | zhipu | 智谱部分模型可支持免费调用 | 免费服务的并发数不要设置过高,建议设置为6以内 |
| 高质量服务 | aliyunDashScope | 翻译效果较好,新用户有赠送额度,可以尝试 | 选择LLM API配置管理中的默认模型选项 |
| 高质量服务 | deepseek(推荐) | 翻译效果好,有缓存命中机制 | 推荐 deepseek-v4-flash;默认关闭思考。手动开启思考需要 pdf2zh_next >= 2.9.0 |
除了免费服务,您均需要配置自己的API Key和URL才可以使用翻译服务(某些服务不需要配置URL,可以忽略)
您可以根据实际情况自行调整并发数
openailiked服务选项可以填写所有兼容openai格式的LLM服务, 您需要填写您的LLM服务供应商提供的URL, API Key, Model名称等信息。
https://ark.cn-beijing.volces.com/api/v3在Zotero中对条目/PDF右键,选择PDF2zh-翻译选项,进行翻译。
对条目/附件单击右键, 可以看到四个翻译选项:
💡 翻译选项解析
| 翻译选项 | 解释 | 示例图片 |
|---|---|---|
| 翻译PDF (translate PDF) | 点击原文PDF或论文条目, 将会生成在Zotero插件设置端所选择的默认生成文件 | ![]() |
| 裁剪PDF (crop PDF) | 选择dual/mono类型附件, 将会对选择的附件在宽度1/2处裁剪, 然后上下拼接, 此功能适合手机阅读 注意事项: 1. 本选项会将页面两侧空白处进行裁剪 2. 若产生截断了原文内容的情况, 可将 server/utils/config.py中的config.pdf_w_offset值降低 | ![]() |
| 双语对照 (compare PDF) | 点击此选项, 会生成左边为原文, 右边为翻译后文本的PDF 1. 选择"Dual文件翻译页在前"可以交换生成顺序 2. 此选项等同于翻译引擎为pdf2zh_next, 且 双语(Dual)文件显示模式为Left&Right时生成的文件 | ![]() |
| 双语对照(裁剪) (crop-compare PDF) | 此选项仅针对双栏PDF论文。它会先将PDF竖向裁剪为单栏文件,再左右拼接。 | ![]() |
您可以多选条目,右键菜单,然后进行批量PDF翻译
插件可以通过 Zotero 检查更新。Server 源码启动时会检查 GitHub/Gitee(优先用 --update_source,失败自动换另一个)。
Python 翻译环境(pdf2zh_next / BabelDOC)是另一件事。普通用户只需在 server 目录运行:
python update_packages.py
它会沿用已有 uv/conda,在当前环境里安装 pdf2zh_next >= 2.9.0,<3.0.0。如果已经是 2.9.0 或更高,启动时不会再询问。不要再手工创建 staging / backup 环境。
Windows Conda 的 Python 在 <env>\python.exe;找不到时会用 conda run 确认真实路径。
如果您不想配置Python虚拟环境,可以直接使用pdf2zh_next 提供的预编译exe版本。
安装步骤:
下载exe包:访问 pdf2zh_next Release 页面,下载 pdf2zh-v2.x.x-BabelDOC-v0.x.x-win64.zip(选择 with-assets 版本)
解压文件:将下载的zip文件解压到 server 目录下,
server/pdf2zh-v2.x.x-BabelDOC-v0.x.x-win64/pdf2zh/pdf2zh.exepython server.py --enable_winexe=True --winexe_path='./pdf2zh-v2.x.x-BabelDOC-v0.x.x-win64/pdf2zh/pdf2zh.exe'
注意事项:
server 目录如果您只想使用 pdf2zh_next/pdf2zh 引擎中的一个,并且全局 Python 版本为 3.12.0,可以不使用虚拟环境管理。
⚠️ 注意:不使用虚拟环境管理时,您需要确保:
- 全局 Python 版本为 3.12 或更高
- 已手动安装所需的依赖包
# 创建固定主虚拟环境(只需执行一次)
uv venv zotero-pdf2zh-server --python 3.12
# 激活环境
# Windows
.\zotero-pdf2zh-server\Scripts\activate
# macOS/Linux
source ./zotero-pdf2zh-server/bin/activate
# 安装依赖
pip install -r requirements.txt
# 启动服务
python server.py --enable_venv=False
# 创建主虚拟环境(只需执行一次)
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 --enable_venv=False
# 如果只使用 pdf2zh:
pip install pdf2zh==1.9.11 numpy==2.2.0
# 如果只使用 pdf2zh_next:
pip install pdf2zh_next
每次翻译都需要打开终端执行启动命令,为了方便日常使用,您可以配置一键启动:
方式一:使用 uv 的用户
Windows 用户 - 创建桌面快捷脚本:
cd 命令查看完整路径cd
终端会显示类似:D:\zotero-pdf2zh\server 的路径
@echo off
cd /d <粘贴刚才复制的路径>
uv run --python 3.12 --with-requirements requirements.txt server.py
pause
将 <粘贴刚才复制的路径> 替换为您复制的实际路径
重命名为 start-pdf2zh.bat(后缀名必须是 .bat)
保存后双击即可启动
macOS / Linux 用户 - 配置别名(alias):
# 如果使用 zsh(macOS 默认)
nano ~/.zshrc
# 如果使用 bash
nano ~/.bashrc
alias pdf2zh-start='cd /path/to/zotero-pdf2zh/server && uv run --python 3.12 --with-requirements requirements.txt server.py'
source ~/.zshrc
# 或
source ~/.bashrc
pdf2zh-start 即可一键启动方式二:使用 conda 的用户
Windows 用户 - 创建桌面快捷脚本:
cd 命令查看完整路径cd
终端会显示类似:D:\zotero-pdf2zh\server 的路径
@echo off
cd /d <粘贴刚才复制的路径>
python server.py --env_tool=conda
pause
将 <粘贴刚才复制的路径> 替换为您复制的实际路径
重命名为 start-pdf2zh-conda.bat(后缀名必须是 .bat)
保存后双击即可启动
macOS / Linux 用户 - 配置别名(alias):
# 如果使用 zsh(macOS 默认)
nano ~/.zshrc
# 如果使用 bash
nano ~/.bashrc
alias pdf2zh-start='cd /path/to/zotero-pdf2zh/server && python server.py --env_tool=conda'
💡 注意:使用此别名前,请确保已初始化 conda(通常在安装 conda 后会自动添加到
.bashrc或.zshrc中)
source ~/.zshrc
# 或
source ~/.bashrc
pdf2zh-start 即可一键启动【🔥高频问题】Q:我遇到了网络问题(NetworkError when attempting to fetch resource),该怎么办?
A:
python server.py --port=9999【🔥高频问题】Q: 翻译卡在某个地方不动了 / pdf2zh_next第一次翻译时进度条一直卡在某一处(例如10/100)/ 出现assets download failed问题
A:
http://127.0.0.1:7860/),翻译一篇文章后退出。为什么这样做是有效的:
【🔥高频问题】Q:我遇到了““动态链接库(DLL)初始化例程失败”的错误,但是我尝试安装了提示中指定的vs_redist.x64.exe包,依然报错,该怎么办?
A:
1.16.1版本
zotero-pdf2zh-venvzotero-pdf2zh-next-venv
【🔥高频问题】Q: 我的命令行中提示: Failed to canonicalize script path
A: 删除server路径下的zotero-pdf2zh-next-venv或者zotero-pdf2zh-venv文件夹, 然后重新配置。使用uv方法在安装配置后不可以修改路径名/移动文件夹。
Q:我没配置API,可以用吗?
A:不可以,除非您使用的是免费的服务。
【🔥高频问题】Q:我正在使用bing/google,也是免费的,但是翻译到一半就报错了/卡住了/中止了
A:
因为bing/google的限流较为严重,您需要把线程数设置得非常低。
建议您最好换到更加稳定的服务,以便长期使用。
Q:我感觉这个翻译消耗的Token很多,怎么办?
A:
【🔥高频问题】Q:翻译后部分段落缺失(未被翻译),该怎么办?
A:
【🔥高频问题】Q1:翻译界面提示 Scanned PDF detected, 翻译失败
A:
Q2:pdf2zh_next服务中的ocr模式与兼容模式是指什么?
A:
*_enable_json_mode(默认关闭),例如 openai_enable_json_mode、deepseek_enable_json_mode。提问前请先尝试以下方法:
如需在群内提问,请提供:
终端完整输出(复制到txt文件)
Zotero设置截图
Zotero弹窗截图
说明您已尝试过的解决方法
Q:我在群里问问题,怎么没人回复我?
A:
Q:可是我给作者打赏了,希望能得到优先支持。
A:非常感谢您的支持!打赏是对项目的肯定和鼓励,如果打赏后遇到问题,欢迎私聊群主,我会尽力协助您解决。
沉浸式翻译为本项目的活跃贡献者赞助每月Pro会员兑换码,详情请见:CONTRIBUTOR_REWARD.md
关于贡献者和赞助者名单更新:本部分名单更新进度稍慢,但是一定会保证更新每一位赞助者和开发者的信息!
📢: 桌面端构建中(Coming Soon!),改动较大,有新的功能&修复了旧bug,暂不接收新的Pull Request
感谢各位贡献者对项目的付出!!
贡献者名单:
💐 免费开源插件,您的支持是我继续开发的动力~祝您科研/工作/学习顺利!
赞助时, 请在备注中留下您希望出现在赞助者名单的姓名或昵称💗
🐳 爱发电
🤖 【SiliconFlow邀请链接】: https://cloud.siliconflow.cn/i/WLYnNanQ
🤖 【方舟Coding Plan邀请链接】: 方舟 Coding Plan 支持 Doubao、GLM、DeepSeek、Kimi 等模型,工具不限,现在订阅折上9折,低至8.9元,订阅越多越划算!立即订阅:https://volcengine.com/L/nVFMmMWNd6U/ 邀请码:8EYCPKHC
🤖 【GLM Coding Plan邀请链接】: 🚀 速来拼好模,智谱 GLM Coding 超值订阅,邀您一起薅羊毛!Claude Code、Cline 等 20+ 大编程工具无缝支持,“码力”全开,越拼越爽!立即开拼,享限时惊喜价!链接:https://www.bigmodel.cn/glm-coding?ic=44Y4L3RHPG
赞助者名单(持续更新), 按照时间先后排序:

本项目采用开源协议发布,所有开发者在使用本插件代码时必须遵循以下原则:
遵守开源协议:使用本项目的代码必须遵循本项目所采用的AGPL开源协议(详见 LICENSE 文件),包括但不限于保留版权声明、开源修改后的代码等。
禁止商业倒卖:本插件为免费开源项目,严禁任何形式的商业倒卖行为,包括但不限于:
⚠️ 特别提醒:商业贩子请勿加入QQ群提问,不要消耗维护者的精力。一旦发现,将直接移出群聊并拉黑。
合理使用:欢迎个人学习、研究、非商业用途的使用。如需商业使用,请联系作者获取授权。
尊重开源精神:我们鼓励开发者基于本项目进行改进和贡献,但请尊重原作者的劳动成果,遵守开源社区的基本准则。
如发现违反上述原则的行为,作者保留追究法律责任的权利。
Python
53.8%
HTML
19.6%
TypeScript
14.3%
Shell
4.3%
JavaScript
2.2%
PowerShell
1.8%
Batchfile
1.7%
Fluent
1.5%
在 Zotero 中直接使用 PDF2zh 与 PDF2zh_next 翻译 PDF,保留公式与排版,并提供双语对照、裁剪阅读、批量翻译与多种 LLM 服务配置。
📚 项目文档: zotero-pdf2zh.github.io
📝 其他语言 / Other Languages:
English | 日本語 | 한국어 | Italiano | Français
Note: The translations above were generated by AI and may contain inaccuracies. For the most accurate information, please refer to this document.
🚀 v4.1.7:远程/Docker 翻译完成后优先 HTTP 挂附件;新旧插件协议兼容;进度条显示翻译百分比;加固附件文件名;补齐 pdf2zh_next 额外字段(含
*_enable_json_mode),LLM 编辑器可从下拉列表添加,默认不开启 JSON mode。请同时更新插件和 Server。🚀 v4.1.6:翻译改为后台任务,避免 Windows 长连接 Network Error;进度查询不再打断终端进度条。
🚀 v4.1.5:修复 Windows 翻译中途 Network Error;进度查询不再打断终端进度条。请同时更新插件和 Server。
🚀 v4.1.4:翻译完成后优先从本机挂附件;终端进度条按窗口宽度绘制。
🚀 v4.1.2:支持 GitHub / Gitee 双源更新和启动通知;DeepSeek V4 默认不思考。
🚀 v4.1.1:修复 Windows Conda 路径、环境误判,以及控制台日志崩溃。
🚀 v4.1.0:支持 DeepSeek V4;自动识别 uv/conda 并在当前环境更新;完善 Dual / Crop 相关处理。
📢 重要通知(2026年8月19日): 本插件正在进行全面重构,预期九月份发布新版本,暂时不会在群里及时解答目前版本相关的问题,请自行向AI提问或阅读本文档~也请开发者暂时不要对本仓库提交贡献,因为无法和新版本进行合并。
📦 下载最新版本: Zotero 插件 XPI · Server · 完整文档
本指南将引导您完成 Zotero PDF2zh 插件的安装和配置。
❓ 遇到问题
pdf2zh_next < 2.9.0,首次启动本版本会询问是否更新;已经 >=2.9.0 则跳过。DeepSeek V4 默认不思考,旧环境可以继续翻译;只有手动开启思考才需要 2.9.0。
N、更新失败,或希望主动维护环境,可在 server 目录运行 python update_packages.py。该命令会沿用已有 uv/conda;没有现有环境时优先 uv。Python:下载链接,建议安装 3.12 版本
Zotero:支持 Zotero 7、Zotero 8、Zotero 9和Zotero 10,如无意外插件会持续支持最新版本,如果Zotero内自动更新失败,请下载最新插件文件重新安装尝试。
打开命令行工具(后续步骤都在命令行中执行):
Win + R → 输入 cmd → 回车(建议以管理员身份运行)Cmd + 空格 → 输入"终端" → 回车Ctrl + Alt + T选择一个环境管理工具。如果不确定选哪个,推荐 uv。
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,能看到版本号即成功。
如果提示找不到命令,需将 uv 路径添加到环境变量并重启终端:
# MacOS/Linux
export PATH="$HOME/.local/bin:$PATH"
# Windows PowerShell
$env:Path = "$env:USERPROFILE\.local\bin;$env:Path"
conda安装
参考 Miniconda 安装指南进行安装,安装后执行 conda --version 验证。
⚠️ Windows用户注意:请勿在C盘(系统盘)下创建项目文件夹,建议在D盘或其他非系统盘操作。例如:先执行
D:切换到D盘,再执行后续命令。
# 1. 创建并进入zotero-pdf2zh文件夹
mkdir zotero-pdf2zh && cd zotero-pdf2zh
# 2. 下载并解压server文件夹
# GitHub 下载失败时,可改用 Gitee: https://gitee.com/guaguastandup/zotero-pdf2zh/raw/v4.1.7/server.zip
# 不要下载 Gitee 源码归档 repository/archive/*.zip(经常是 HTML 登录/验证页)
wget https://github.com/guaguastandup/zotero-pdf2zh/releases/latest/download/server.zip
unzip server.zip
# 3. 进入server文件夹
cd server
💡 提示:确认目录结构
解压后,请确认您的目录结构应该是:
zotero-pdf2zh/ └── server/ ├── server.py ├── ... └── requirements.txt如果您看到的是
server/server/这样的嵌套结构(两层 server),说明解压出现了嵌套问题,请执行:# 回到上级目录 cd .. # 移动内容到正确位置 mv server/server/* server/ # 删除空的嵌套目录 rmdir server/server # 重新进入 server 目录 cd server
快速检查方法:
执行 cd server 后,运行 ls server.py,如果能看到 server.py 文件,说明目录结构正确。如果提示找不到文件,说明存在嵌套问题。
uv 用户(推荐)
uv run --python 3.12 --with-requirements requirements.txt server.py
conda 用户
# 1. 创建环境(仅首次需要)
conda create -n zotero-pdf2zh-server python=3.12 -y
# 2. 激活环境
conda activate zotero-pdf2zh-server
# 3. 安装依赖(仅首次需要)
pip install -r requirements.txt
# 4. 启动服务
python server.py --env_tool=conda
⚠️ 重要:翻译功能依赖本脚本运行,使用翻译时不要关闭此终端窗口。
在启动命令后面追加参数即可,例如 ... server.py --port=9999:
| 参数 | 说明 | 默认值 |
|---|---|---|
--host | Server 监听地址;默认仅本机访问,远程部署时才使用 0.0.0.0 | 127.0.0.1 |
--port | 服务端口号 | 8890 |
--check_update | 启动时检查更新 | True |
--update_source | 优先更新源(github / gitee)。会两个都试,失败自动换另一个 | gitee |
--enable_mirror | 启用 pip 镜像加速 | True |
--mirror_source | 自定义镜像源 URL | https://mirrors.ustc.edu.cn/pypi/simple |
--enable_winexe | 使用 Windows exe 模式(需配合 --winexe_path) | False |
server 文件夹(会影响环境路径)。server 文件夹。新版 Server/update_packages.py 会自动沿用已有 conda 环境;新安装仍优先 uv。127.0.0.1。确实需要其他设备访问时显式添加 --host 0.0.0.0,并自行配置防火墙/可信网络。最新版本 v4.1.7 下载链接

检查服务器连接
在插件设置页面中,点击"Python Server IP"输入框旁边的"检查连接"按钮,可测试与Python服务的连接状态。若显示连接成功,则服务正常运行;若显示连接失败,请检查:
配置选项说明
切换翻译引擎pdf2zh/pdf2zh_next,界面将显示不同引擎的翻译配置
其他说明(初次配置可以忽略)
关于qps(Query Per Second)和poolsize选项:
具体数值请参考您的LLM服务商提供的参数(例如zhipu)
- 计算公式:
qps = rpm / 60(RPM = Request Per Minute)- 对于上游为qps/rpm限速:pool size = qps * 10;
- 对于上游为并发数限制: pool size = max(向下取整(0.9*官方并发数限制), 官方并发数限制-20),qps = pool size
- 如果您不知道怎么设置, 请直接设置qps即可, pool size设置为默认值0即可
翻译引擎pdf2zh的自定义字体:
- 字体文件路径为本地路径。
- 如果采用远端服务器部署,暂时无法在插件设置中指定字体路径。需要您手动修改
config.json文件中的NOTO_FONT_PATH字段。
额外配置参数名需要与 config 文件中的字段相同。v4.1.7 起,在「LLM API配置管理」里点「添加参数」,可从当前服务支持的字段下拉选择(也可选「自定义」手填)。OpenAI / DeepSeek / SiliconFlow 等支持 *_enable_json_mode(如 openai_enable_json_mode、deepseek_enable_json_mode),默认关闭;部分模型漏译段落时可尝试设为 true。字段说明见 额外参数文档 与 extraData.md
网页端查看翻译进度
服务启动后,可在浏览器中访问 http://127.0.0.1:8890 查看翻译进度和使用相关功能:



功能说明:
📢: v4.0.3(3月7日) windows端暂时不支持多进度条显示(多个pdf同时翻译时只会有一个进度条会更新,是bug待修复)
翻译引擎对比
插件支持两种翻译引擎,请根据需求选择:
| 对比项 | PDF2ZH (旧版) | PDF2ZH Next (新版) |
|---|---|---|
| 维护状态 | ❌ 不再活跃维护 | ✅ 持续更新维护 |
| 翻译速度 | ⚡ 较快 | 速度适中 |
| 自定义字体 | ✅ 支持更换自定义字体 | ❌ 不支持 |
| 配置文件 | config.json | config.toml |
| 双语模式 | 默认为Top&Bottom | 默认为 Left&Right |
| 术语表功能 | ❌ 不支持 | ✅ 自动提取并使用术语表 |
| 表格翻译 | ❌ 不支持 | ✅ 支持表格内容翻译 |
| OCR兼容 | ❌ 不支持 | ✅ 支持 OCR 兼容模式和自动 OCR |
| 支持的翻译服务 | 支持海量翻译服务 | 提供免费 siliconflowfree |
| 上游项目 | Byaidu/PDFMathTranslate | PDFMathTranslate-next |
翻译服务配置
配置翻译服务需完成两步:
第一步:添加API配置
在"LLM API配置管理"区域点击"新增",填写服务配置信息。同一服务可添加多个配置,但只能激活其中一个。
第二步:选择翻译服务
在页面顶部的"翻译服务"下拉菜单中,选择要使用的服务名称。
警告:仅添加API配置不会生效,必须完成第二步选择服务,翻译功能才能使用。
💡 翻译服务介绍(必读)
| 服务类型 | 服务名称 | 服务介绍 | 💡注意事项 |
|---|---|---|---|
| 免费&免配置的翻译服务 | siliconflowfree | 基于硅基流动提供的GLM4-9B模型, 仅支持翻译引擎pdf2zh_next,由@硅基流动、@pdf2zh_next 和 @BabelDOC联合提供服务 | 1. 此服务无需选择qps,默认为20 2.此服务可能会存在漏翻译的情况,如果需要高质量翻译请优先选择其他服务 3. 此服务仅支持pdf2zh_next引擎 |
| 免费&免配置的翻译服务 | bing/google | bing/google的官方机器翻译 | bing和goole的翻译服务都存在限流,如果翻译失败,请将并发数设置调至2及以下重试 |
| 具有优惠/赠送的翻译服务 | openaliked | 加入火山引擎协作计划,个人用户每个模型每天最多赠送50w token | 1. 协作计划的额度赠送规则是:按照前一天参加协作的token量等额计算(例如您昨天使用了10w token,那么今天的赠送额度则为10w token)上限为50w,请注意检查自己的额度使用情况,避免超额 2. 此服务支持高并发数:可设置并发数为500~1000 |
| 具有优惠/赠送的翻译服务 | silicon | 通过邀请好友可以获得14元赠送金额 | 1. 此服务url需填写为: https://api.siliconflow.cn/v1,如果后面有completions等后缀,请删除。2. 此服务免费版支持的线程数较低,建议设置为6左右 |
| 具有优惠/赠送的翻译服务 | zhipu | 智谱部分模型可支持免费调用 | 免费服务的并发数不要设置过高,建议设置为6以内 |
| 高质量服务 | aliyunDashScope | 翻译效果较好,新用户有赠送额度,可以尝试 | 选择LLM API配置管理中的默认模型选项 |
| 高质量服务 | deepseek(推荐) | 翻译效果好,有缓存命中机制 | 推荐 deepseek-v4-flash;默认关闭思考。手动开启思考需要 pdf2zh_next >= 2.9.0 |
除了免费服务,您均需要配置自己的API Key和URL才可以使用翻译服务(某些服务不需要配置URL,可以忽略)
您可以根据实际情况自行调整并发数
openailiked服务选项可以填写所有兼容openai格式的LLM服务, 您需要填写您的LLM服务供应商提供的URL, API Key, Model名称等信息。
https://ark.cn-beijing.volces.com/api/v3在Zotero中对条目/PDF右键,选择PDF2zh-翻译选项,进行翻译。
对条目/附件单击右键, 可以看到四个翻译选项:
💡 翻译选项解析
| 翻译选项 | 解释 | 示例图片 |
|---|---|---|
| 翻译PDF (translate PDF) | 点击原文PDF或论文条目, 将会生成在Zotero插件设置端所选择的默认生成文件 | ![]() |
| 裁剪PDF (crop PDF) | 选择dual/mono类型附件, 将会对选择的附件在宽度1/2处裁剪, 然后上下拼接, 此功能适合手机阅读 注意事项: 1. 本选项会将页面两侧空白处进行裁剪 2. 若产生截断了原文内容的情况, 可将 server/utils/config.py中的config.pdf_w_offset值降低 | ![]() |
| 双语对照 (compare PDF) | 点击此选项, 会生成左边为原文, 右边为翻译后文本的PDF 1. 选择"Dual文件翻译页在前"可以交换生成顺序 2. 此选项等同于翻译引擎为pdf2zh_next, 且 双语(Dual)文件显示模式为Left&Right时生成的文件 | ![]() |
| 双语对照(裁剪) (crop-compare PDF) | 此选项仅针对双栏PDF论文。它会先将PDF竖向裁剪为单栏文件,再左右拼接。 | ![]() |
您可以多选条目,右键菜单,然后进行批量PDF翻译
插件可以通过 Zotero 检查更新。Server 源码启动时会检查 GitHub/Gitee(优先用 --update_source,失败自动换另一个)。
Python 翻译环境(pdf2zh_next / BabelDOC)是另一件事。普通用户只需在 server 目录运行:
python update_packages.py
它会沿用已有 uv/conda,在当前环境里安装 pdf2zh_next >= 2.9.0,<3.0.0。如果已经是 2.9.0 或更高,启动时不会再询问。不要再手工创建 staging / backup 环境。
Windows Conda 的 Python 在 <env>\python.exe;找不到时会用 conda run 确认真实路径。
如果您不想配置Python虚拟环境,可以直接使用pdf2zh_next 提供的预编译exe版本。
安装步骤:
下载exe包:访问 pdf2zh_next Release 页面,下载 pdf2zh-v2.x.x-BabelDOC-v0.x.x-win64.zip(选择 with-assets 版本)
解压文件:将下载的zip文件解压到 server 目录下,
server/pdf2zh-v2.x.x-BabelDOC-v0.x.x-win64/pdf2zh/pdf2zh.exepython server.py --enable_winexe=True --winexe_path='./pdf2zh-v2.x.x-BabelDOC-v0.x.x-win64/pdf2zh/pdf2zh.exe'
注意事项:
server 目录如果您只想使用 pdf2zh_next/pdf2zh 引擎中的一个,并且全局 Python 版本为 3.12.0,可以不使用虚拟环境管理。
⚠️ 注意:不使用虚拟环境管理时,您需要确保:
- 全局 Python 版本为 3.12 或更高
- 已手动安装所需的依赖包
# 创建固定主虚拟环境(只需执行一次)
uv venv zotero-pdf2zh-server --python 3.12
# 激活环境
# Windows
.\zotero-pdf2zh-server\Scripts\activate
# macOS/Linux
source ./zotero-pdf2zh-server/bin/activate
# 安装依赖
pip install -r requirements.txt
# 启动服务
python server.py --enable_venv=False
# 创建主虚拟环境(只需执行一次)
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 --enable_venv=False
# 如果只使用 pdf2zh:
pip install pdf2zh==1.9.11 numpy==2.2.0
# 如果只使用 pdf2zh_next:
pip install pdf2zh_next
每次翻译都需要打开终端执行启动命令,为了方便日常使用,您可以配置一键启动:
方式一:使用 uv 的用户
Windows 用户 - 创建桌面快捷脚本:
cd 命令查看完整路径cd
终端会显示类似:D:\zotero-pdf2zh\server 的路径
@echo off
cd /d <粘贴刚才复制的路径>
uv run --python 3.12 --with-requirements requirements.txt server.py
pause
将 <粘贴刚才复制的路径> 替换为您复制的实际路径
重命名为 start-pdf2zh.bat(后缀名必须是 .bat)
保存后双击即可启动
macOS / Linux 用户 - 配置别名(alias):
# 如果使用 zsh(macOS 默认)
nano ~/.zshrc
# 如果使用 bash
nano ~/.bashrc
alias pdf2zh-start='cd /path/to/zotero-pdf2zh/server && uv run --python 3.12 --with-requirements requirements.txt server.py'
source ~/.zshrc
# 或
source ~/.bashrc
pdf2zh-start 即可一键启动方式二:使用 conda 的用户
Windows 用户 - 创建桌面快捷脚本:
cd 命令查看完整路径cd
终端会显示类似:D:\zotero-pdf2zh\server 的路径
@echo off
cd /d <粘贴刚才复制的路径>
python server.py --env_tool=conda
pause
将 <粘贴刚才复制的路径> 替换为您复制的实际路径
重命名为 start-pdf2zh-conda.bat(后缀名必须是 .bat)
保存后双击即可启动
macOS / Linux 用户 - 配置别名(alias):
# 如果使用 zsh(macOS 默认)
nano ~/.zshrc
# 如果使用 bash
nano ~/.bashrc
alias pdf2zh-start='cd /path/to/zotero-pdf2zh/server && python server.py --env_tool=conda'
💡 注意:使用此别名前,请确保已初始化 conda(通常在安装 conda 后会自动添加到
.bashrc或.zshrc中)
source ~/.zshrc
# 或
source ~/.bashrc
pdf2zh-start 即可一键启动【🔥高频问题】Q:我遇到了网络问题(NetworkError when attempting to fetch resource),该怎么办?
A:
python server.py --port=9999【🔥高频问题】Q: 翻译卡在某个地方不动了 / pdf2zh_next第一次翻译时进度条一直卡在某一处(例如10/100)/ 出现assets download failed问题
A:
http://127.0.0.1:7860/),翻译一篇文章后退出。为什么这样做是有效的:
【🔥高频问题】Q:我遇到了““动态链接库(DLL)初始化例程失败”的错误,但是我尝试安装了提示中指定的vs_redist.x64.exe包,依然报错,该怎么办?
A:
1.16.1版本
zotero-pdf2zh-venvzotero-pdf2zh-next-venv
【🔥高频问题】Q: 我的命令行中提示: Failed to canonicalize script path
A: 删除server路径下的zotero-pdf2zh-next-venv或者zotero-pdf2zh-venv文件夹, 然后重新配置。使用uv方法在安装配置后不可以修改路径名/移动文件夹。
Q:我没配置API,可以用吗?
A:不可以,除非您使用的是免费的服务。
【🔥高频问题】Q:我正在使用bing/google,也是免费的,但是翻译到一半就报错了/卡住了/中止了
A:
因为bing/google的限流较为严重,您需要把线程数设置得非常低。
建议您最好换到更加稳定的服务,以便长期使用。
Q:我感觉这个翻译消耗的Token很多,怎么办?
A:
【🔥高频问题】Q:翻译后部分段落缺失(未被翻译),该怎么办?
A:
【🔥高频问题】Q1:翻译界面提示 Scanned PDF detected, 翻译失败
A:
Q2:pdf2zh_next服务中的ocr模式与兼容模式是指什么?
A:
*_enable_json_mode(默认关闭),例如 openai_enable_json_mode、deepseek_enable_json_mode。提问前请先尝试以下方法:
如需在群内提问,请提供:
终端完整输出(复制到txt文件)
Zotero设置截图
Zotero弹窗截图
说明您已尝试过的解决方法
Q:我在群里问问题,怎么没人回复我?
A:
Q:可是我给作者打赏了,希望能得到优先支持。
A:非常感谢您的支持!打赏是对项目的肯定和鼓励,如果打赏后遇到问题,欢迎私聊群主,我会尽力协助您解决。
沉浸式翻译为本项目的活跃贡献者赞助每月Pro会员兑换码,详情请见:CONTRIBUTOR_REWARD.md
关于贡献者和赞助者名单更新:本部分名单更新进度稍慢,但是一定会保证更新每一位赞助者和开发者的信息!
📢: 桌面端构建中(Coming Soon!),改动较大,有新的功能&修复了旧bug,暂不接收新的Pull Request
感谢各位贡献者对项目的付出!!
贡献者名单:
💐 免费开源插件,您的支持是我继续开发的动力~祝您科研/工作/学习顺利!
赞助时, 请在备注中留下您希望出现在赞助者名单的姓名或昵称💗
🐳 爱发电
🤖 【SiliconFlow邀请链接】: https://cloud.siliconflow.cn/i/WLYnNanQ
🤖 【方舟Coding Plan邀请链接】: 方舟 Coding Plan 支持 Doubao、GLM、DeepSeek、Kimi 等模型,工具不限,现在订阅折上9折,低至8.9元,订阅越多越划算!立即订阅:https://volcengine.com/L/nVFMmMWNd6U/ 邀请码:8EYCPKHC
🤖 【GLM Coding Plan邀请链接】: 🚀 速来拼好模,智谱 GLM Coding 超值订阅,邀您一起薅羊毛!Claude Code、Cline 等 20+ 大编程工具无缝支持,“码力”全开,越拼越爽!立即开拼,享限时惊喜价!链接:https://www.bigmodel.cn/glm-coding?ic=44Y4L3RHPG
赞助者名单(持续更新), 按照时间先后排序:

本项目采用开源协议发布,所有开发者在使用本插件代码时必须遵循以下原则:
遵守开源协议:使用本项目的代码必须遵循本项目所采用的AGPL开源协议(详见 LICENSE 文件),包括但不限于保留版权声明、开源修改后的代码等。
禁止商业倒卖:本插件为免费开源项目,严禁任何形式的商业倒卖行为,包括但不限于:
⚠️ 特别提醒:商业贩子请勿加入QQ群提问,不要消耗维护者的精力。一旦发现,将直接移出群聊并拉黑。
合理使用:欢迎个人学习、研究、非商业用途的使用。如需商业使用,请联系作者获取授权。
尊重开源精神:我们鼓励开发者基于本项目进行改进和贡献,但请尊重原作者的劳动成果,遵守开源社区的基本准则。
如发现违反上述原则的行为,作者保留追究法律责任的权利。
Python
53.8%
HTML
19.6%
TypeScript
14.3%
Shell
4.3%
JavaScript
2.2%
PowerShell
1.8%
Batchfile
1.7%
Fluent
1.5%