
Zotero PDF2zh



在 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 插件的安装和配置。
❓ 遇到问题
- 跳转至本项目总结的常见问题:常见问题(FAQ)
- 基础问题(例如如何安装python,如何安装conda等问题)请向AI提问
- 在github issue区提问
- QQ群提问:
- 提问时需要遵循规则: 确保已经阅读过issue区和常见问题文档,重复问题不会得到回复。确定问题为新问题后, 将终端报错复制到txt文件, 并截图zotero插件设置端配置
- 1群: 971960014(已满)
- 2群: 897867369(已满)
- 3群: 1064375380(已满)
- 4群: 443031486(已满)
- 5群: 1064435415(已满)
- 6群: 1083772600(已满)
- 7群: 930368730(已满)
- 8群: 1093571926(已满)
- 9群: 1108984892
- 入群口令: github
- 📢 v4.1.7 升级提示:请同时更新插件和 Server。
- 📢 翻译环境:已有用户若
pdf2zh_next < 2.9.0,首次启动本版本会询问是否更新;已经 >=2.9.0 则跳过。DeepSeek V4 默认不思考,旧环境可以继续翻译;只有手动开启思考才需要 2.9.0。
- 🔧 如果之前选择了
N、更新失败,或希望主动维护环境,可在 server 目录运行 python update_packages.py。该命令会沿用已有 uv/conda;没有现有环境时优先 uv。
- 📢 重要通知(2026年8月19日): 本插件正在进行全面重构,预期九月份发布新版本,暂时不会在群里及时解答目前版本相关的问题,请自行向AI提问或阅读本文档~也请开发者暂时不要对本仓库提交贡献,因为无法和新版本进行合并。
安装说明
第零步:安装Python和Zotero
第一步:安装uv/conda
选择一个环境管理工具。如果不确定选哪个,推荐 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 |
注意事项
- uv 用户:安装后请不要移动或重命名
server 文件夹(会影响环境路径)。
- conda 用户:环境存储在 conda 的 envs 目录中,可以安全移动
server 文件夹。新版 Server/update_packages.py 会自动沿用已有 conda 环境;新安装仍优先 uv。
- 远程 Server 用户:默认只监听
127.0.0.1。确实需要其他设备访问时显式添加 --host 0.0.0.0,并自行配置防火墙/可信网络。
第四步:下载并安装插件
最新版本 v4.1.7 下载链接
- 安装方式:在zotero中打开“工具-插件”,将xpi文件拖入,进行安装。(若拖入后功能未生效,请重启Zotero)
- 如何更新:您可以在zotero中检查更新,或选择自动更新,来获取最新版本插件。
第五步:Zotero端插件设置
zotero 插件设置页面
检查服务器连接
在插件设置页面中,点击"Python Server IP"输入框旁边的"检查连接"按钮,可测试与Python服务的连接状态。若显示连接成功,则服务正常运行;若显示连接失败,请检查:
- server.py 脚本是否正在运行
- 端口号是否正确(默认8890)
- 防火墙/杀毒软件是否阻止了连接
配置选项说明
网页端查看翻译进度
服务启动后,可在浏览器中访问 http://127.0.0.1:8890 查看翻译进度和使用相关功能:
查看当前配置信息
实时查看翻译进度
查看历史翻译记录并预览下载
功能说明:
- 查看当前server端的配置信息
- 实时显示当前翻译任务状态
- 查看翻译历史记录,支持预览和下载翻译后的文件
📢: 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名称等信息。
- 示例: 火山引擎url填写为
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 确认真实路径。
其他安装方法
Windows exe 版本安装(仅限Windows用户)
如果您不想配置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.exe
- 运行服务:
python server.py --enable_winexe=True --winexe_path='./pdf2zh-v2.x.x-BabelDOC-v0.x.x-win64/pdf2zh/pdf2zh.exe'
注意事项:
Docker 部署
Homebrew/Linuxbrew 部署(MacOS/Linux用户)
不使用虚拟环境管理
如果您只想使用 pdf2zh_next/pdf2zh 引擎中的一个,并且全局 Python 版本为 3.12.0,可以不使用虚拟环境管理。
⚠️ 注意:不使用虚拟环境管理时,您需要确保:
- 全局 Python 版本为 3.12 或更高
- 已手动安装所需的依赖包
uv 用户(推荐)
# 创建固定主虚拟环境(只需执行一次)
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 用户
# 创建主虚拟环境(只需执行一次)
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):
- 打开终端,编辑 shell 配置文件:
# 如果使用 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):
- 打开终端,编辑 shell 配置文件:
# 如果使用 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 即可一键启动
常见问题(FAQ)
关于网络
关于环境
-
【🔥高频问题】Q:我遇到了““动态链接库(DLL)初始化例程失败”的错误,但是我尝试安装了提示中指定的vs_redist.x64.exe包,依然报错,该怎么办?
-
A:
- 您需要进入虚拟环境,将onnx包降级到
1.16.1版本
- pdf2zh 对应的虚拟环境名为
zotero-pdf2zh-venv
- pdf2zh_next对应的虚拟环境名为
zotero-pdf2zh-next-venv
- 如果您依然不会操作,可以把这段内容发送给AI,并且告诉它您正在使用uv还是conda进行虚拟环境管理。
- 您也许缺少的是x86或其他版本的Visual C++ Redistributable,可以尝试安装以下三个文件:
- 也许您正在使用macOS旧版本系统(这个问题大部分发生在windows系统中),您需要在安装时python虚拟环境指定为3.11而不是3.12
- 另有群友贡献的方法供您尝试:
-
【🔥高频问题】Q: 我的命令行中提示: Failed to canonicalize script path
-
A: 删除server路径下的zotero-pdf2zh-next-venv或者zotero-pdf2zh-venv文件夹, 然后重新配置。使用uv方法在安装配置后不可以修改路径名/移动文件夹。
关于翻译服务
关于OCR/扫描件
关于翻译效果
- Q:为什么会出现段落缺失、断行或重影的情况?
- A:
- 扫描件问题:如果文档本身是扫描件,必须先经过OCR处理后再进行翻译。若未进行OCR识别,会导致断行或段落缺失问题。
- 重影现象:出现的重影通常是由于OCR识别不准确或PDF文件本身的问题导致的。建议使用高质量的OCR工具重新处理文档。
- 段落缺失:如前文所述,翻译失败时程序会用原文替代,建议先排查 API 服务是否正常。使用 pdf2zh_next 时,也可在 LLM 配置的额外参数里开启对应服务的
*_enable_json_mode(默认关闭),例如 openai_enable_json_mode、deepseek_enable_json_mode。
关于插件功能
- Q:我不知道zotero插件里的各个功能是什么意思
- A:您可以自由尝试,请尽量不要对这些问题进行提问,翻译引擎具有缓存的设置,也就是说您重复对同一篇文献进行翻译时,可能不会消耗过多的Token(不能保证完全不消耗)
关于提问
提问前请先尝试以下方法:
- 将终端报错信息发送给AI(ChatGPT、Gemini、DeepSeek等)进行分析
- 在本文档中搜索错误关键词或查阅相关章节
如需在群内提问,请提供:
关于支持本插件
- Q:我很喜欢这个插件,想要提供支持,让这个插件更好地长期运行,我该怎么做?
- A:
- 您可以继续下滑,找到支持本项目开发者的方式(支付码/爱发电等方式,您的昵称将出现在赞助者名单)
- 您可以参与本项目的开发
- 您可以为本项目点一个star
- 您可以在issue区提出您期望的未来功能(需是合理的功能建议)
- 您可以将本插件推荐给身边的朋友,并且在他们的安装过程中给出一些指导
致谢
贡献者
📢: 桌面端构建中(Coming Soon!),改动较大,有新的功能&修复了旧bug,暂不接收新的Pull Request
感谢各位贡献者对项目的付出!!

贡献者名单:

如何支持我
💐 免费开源插件,您的支持是我继续开发的动力~祝您科研/工作/学习顺利!
赞助者名单
感谢您的支持! 您的支持是我开发的动力~
Star History

开源协议与使用声明
本项目采用开源协议发布,所有开发者在使用本插件代码时必须遵循以下原则:
-
遵守开源协议:使用本项目的代码必须遵循本项目所采用的AGPL开源协议(详见 LICENSE 文件),包括但不限于保留版权声明、开源修改后的代码等。
-
禁止商业倒卖:本插件为免费开源项目,严禁任何形式的商业倒卖行为,包括但不限于:
- 将本插件打包后以收费形式出售
- 以"代安装"、"技术服务"等名义收取高额费用后交付本插件
- 将本插件作为付费产品的一部分进行销售
⚠️ 特别提醒:商业贩子请勿加入QQ群提问,不要消耗维护者的精力。一旦发现,将直接移出群聊并拉黑。
-
合理使用:欢迎个人学习、研究、非商业用途的使用。如需商业使用,请联系作者获取授权。
-
尊重开源精神:我们鼓励开发者基于本项目进行改进和贡献,但请尊重原作者的劳动成果,遵守开源社区的基本准则。
如发现违反上述原则的行为,作者保留追究法律责任的权利。
评论