本指南将引导您完成 Zotero PDF2zh 插件的安装和配置。
遇到问题：
- 请先访问：常见问题
- 尝试问一下AI
- 提issue或到插件群发自己的终端报错截图（一定要有终端截图，谢谢！）
- 访问网络上的视频教程，感谢大家的视频教程！
有Docker启动和终端启动两种方法可选。
第一步：创建目录，下载并创建必要文件
# 1. 创建并进入docker文件夹
mkdir docker && cd docker
# 2. 下载docker文件
wget https://github.com/raw/guaguastandup/zotero-pdf2zh/refs/heads/main/Dockerfile
wget https://github.com/raw/guaguastandup/zotero-pdf2zh/refs/heads/main/docker-compose.yaml
# 3. 创建并进入zotero-pdf2zh文件夹
mkdir zotero-pdf2zh && cd zotero-pdf2zh
# 4. 创建translated文件夹，存放翻译输出文件
mkdir translated
# 5. 创建config.json文件(待配置)
echo '{}' > config.json
# 6. 回到docker文件夹
cd ..文件夹结构如下：
docker
├── Dockerfile
├── docker-compose.yaml
└── zotero-pdf2zh
├── config.json
└── translated第二步：构建 Docker 镜像
docker compose build第三步：启动 Docker 容器
-
首次运行（推荐）：在当前终端启动，以便观察 Docker 容器的输出和翻译是否正常
docker compose up
-
后台启动： 在当前终端启动 Docker 程序，程序将挂载在后台（首次执行建议在终端运行，以便观察 PDF 是否正确翻译）
docker compose up -d
第一步：创建目录，存放本插件需要的所有文件
# 1. 创建并进入zotero-pdf2zh文件夹
mkdir zotero-pdf2zh && cd zotero-pdf2zh
# 2. 下载server.py文件
wget https://github.com/raw/guaguastandup/zotero-pdf2zh/refs/heads/main/server.py
# 3. 创建translated文件夹，存放翻译输出文件
mkdir translated
# 4. 创建config.json文件(待配置)
echo '{}' > config.json文件夹结构如下：
zotero-pdf2zh
├── config.json
├── server.py
└── translated第二步：创建虚拟环境并安装需要的包
安装方式请在 conda 或 uv 中选择一种即可。
conda安装
conda create -n zotero-pdf2zh python=3.12 # 创建conda虚拟环境
conda activate zotero-pdf2zh # 启动conda虚拟环境
python -m pip install pdf2zh==1.9.6 flask pypdf # 安装需要的包
python -m pip install pdfminer.six==20250416 # 修正pdfminer安装版本
python -m pip install numpy==2.2.0uv安装
进入zotero-pdf2zh文件夹：
- 安装uv环境
# 方法一: 使用pip安装uv
pip install uv
# 方法二: 下载脚本安装
# macOS/Linux
wget -qO- https://astral.sh/uv/install.sh | sh
# windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"- uv安装Python 3.12
uv python install 3.12 # 安装3.12版本python
uv venv --python 3.12 # 创建3.12版本python虚拟环境- 启动虚拟环境
-
Linux/macOS执行
source .venv/bin/activate -
windows执行
.\.venv\Scripts\activate
-
第三步: 安装需要的包
uv pip install pdf2zh==1.9.6 flask pypdf # 安装需要的包 uv pip install pdfminer.six==20250416 # 修正pdfminer安装版本 uv pip install numpy==2.2.0 # 修正numpy安装版本
第三步：测试pdf2zh安装
在终端直接输入命令:
pdf2zh document.pdf --service bing # document.pdf是待翻译的文件请不要忽略测试步骤。
等待翻译结束，如果失败了，说明上一步的安装出现问题。这一步会使用bing免费服务翻译文件。
本插件当前开发使用的 pdf2zh版本: v1.9.6.
第四步：执行Python脚本
- Conda版本
python server.py 8888- uv版本
uv run server.py 8888💡Tips
- 命令行参数
8888是端口号，您可以自行修改，但请确保该端口是开放的。- 提示： 如果在此步骤中修改了端口号，那么在 Zotero 配置中（第三步），也需要相应地修改 Python 服务器 IP 端口号。
第一步：复制config.json模版
config.json文件示例如下，将此模版替换到第一步中创建的config.json文件内容：
{
"USE_MODELSCOPE": "0",
"PDF2ZH_LANG_FROM": "English",
"PDF2ZH_LANG_TO": "Simplified Chinese",
"NOTO_FONT_PATH": "./LXGWWenKai-Regular.ttf",
"translators": [
{
"name": "deepseek",
"envs": {
"DEEPSEEK_API_KEY": "sk-xxxxxxx",
"DEEPSEEK_MODEL": "deepseek-chat"
}
},
{
"name": "zhipu",
"envs": {
"ZHIPU_API_KEY": "xxxxxx",
"ZHIPU_MODEL": "glm-4-flash"
}
},
{
"name": "openailiked",
"envs": {
"OPENAILIKED_BASE_URL": "https://ark.cn-beijing.volces.com/api/v3",
"OPENAILIKED_API_KEY": "xxxxx",
"OPENAILIKED_MODEL": "ep-xxxx-xxxxx"
}
}
]
}第二步：字体配置
-
将字体文件放在
zotero-pdf2zh， 然后在config.json中，修改自定义字体文件路径"NOTO_FONT_PATH": "./xxxxxx.xxx"(您的字体文件名). -
如果翻译后无法正确显示字体，请先在电脑中安装本字体.
-
推荐下载并使用 霞鹜文楷字体 (LXGWWenKai-Regular.ttf) 或 "微信读书AI楷"(可以在贴吧等社区搜索下载).
-
如果使用docker方法启动，并需要自定义字体，需要进行以下步骤：
- 在
docker-compose.yaml文件中挂载字体文件：
volumes: - ./zotero-pdf2zh/translated:/app/translated - ./zotero-pdf2zh/config.json:/app/config.json - ./zotero-pdf2zh/LXGWWenKai-Regular.ttf:/app/LXGWWenKai-Regular.ttf # 这一行是新添加的字体挂载。- 执行
docker compose up -d，更新容器挂载信息。
- 在
第三步：翻译引擎配置
在config.json文件中，将您申请的LLM API和使用的LLM Model配置输入 translators中。
关于翻译引擎的选择：
- 使用默认的bing或者google，速度快，效果适中，不需要在config.json文件中配置
- 推荐1：在火山引擎中选择
deepseek-v3模型服务（参与协作奖励计划，每天有50w免费额度，需要将自己的推理内容共享给火山引擎)，线程数可设置为200以上， 此服务对应下方实例文件中的openailiked.- 推荐2：智谱AI的
glm-4-flash模型（免费），此服务对应下方实例文件中的zhipu.- 推荐3：deepseek的
deepseek-v3，夜间00:30以后有50%优惠，可以按住shift选择多个条目-右键翻译，并且把线程数调高（20以上），此服务对应下方实例文件中的deepseek.
- 更多配置方法，请参考PDF2zh原文档： PDF2zh Config File
| 选项 | 值 | 备注 |
|---|---|---|
| Python Server IP | 默认为http://localhost:8888 |
其中 8888 为翻译端口号，需与启动脚本时设置的端口号一致。 |
| 源语言 | 默认为en |
翻译源语言，默认为英文。 |
| 目标语言 | 默认为zh |
翻译目标语言，默认为中文。 |
| 翻译引擎 | pdf2zh |
目前仅支持 PDF2zh，无需改动。 |
| 翻译服务 | 默认为bing |
翻译服务，可以从下拉菜单选择或自行输入。与配置文件 config.json 中的 translators 对应。（根据需要调整） |
| 线程数 | 默认为4 |
PDF2zh在翻译时的执行线程数。（根据需要调整） |
| 翻译文件输出路径 | 默认为./translated/ |
用于临时存储翻译得到的 PDF 文件，翻译完成后可以删除。（无需改动） |
| 配置文件路径 | 默认为./config.json |
用于配置翻译引擎和字体。（无需改动） |
| 重命名为短标题 | 默认勾选 | 将新增文件的条目标题命名为短标题，但是不会改变原文件的命名； 命名规则： 短标题-翻译类型-翻译服务名，如果短标题不存在，则命名为翻译类型-翻译服务名。例如vLLM-dual-deepseek。 |
| 启用babeldoc | 默认不勾选 | 是否在PDF2zh中启用babeldoc。 |
| 默认生成翻译 | 默认生成mono和dual文件 | 通过勾选来控制添加到 Zotero 中的文件类型。同时，您可以进一步勾选是否在生成该文件后自动打开。临时文件夹中默认生成 mono（仅目标语言）和 dual（源语言和目标语言）两种文件。 |
| 跳过子集化 | 默认不勾选 | 在翻译正常进行但最终渲染 PDF 失败的情况下，可以考虑勾选此项。 |
| 跳过最后几页 | 默认值为0 | 为了节约 LLM 的 token 用量，可以跳过最后几页引用文献不翻译（目前不支持 babeldoc 模式，如果使用 babeldoc 服务，请将此选项设置为 0）。 |
💡Tips
dual文件中包含源语言和目标语言，mono文件中仅包含目标语言- 以上路径支持绝对路径和相对路径。如果设置为相对路径，则根路径与接下来Python脚本执行的路径一致。
- 举例：如果python脚本在
/home/xxx/server/下执行，翻译输出路径设置为临时路径./translated/，则实际的输出路径为/home/xxx/server/translated/- 一般来说不需要改动本路径，直接使用默认的相对路径即可。
打开Zotero，右键选择条目或者附件。（支持批量选择） 如果选择条目，将会自动选择该条目下创建时间最早的PDF。
选项一：PDF2zh：翻译PDF
本选项生成的文件由Zotero插件设置中的“默认生成文件”勾选项决定，默认生成mono和dual两个文件。
选项二：PDF2zh：裁剪PDF
本选项仅将选中的pdf文件由双栏文件切割为单栏文件。
将双栏论文剪切拼接为单栏显示，适配手机阅读
得到后缀中包含cut的单栏PDF文件，如mono-cut， dual-cut，origin-cut
选项三：PDF2zh：双语对照(双栏)
本选项适用于不启动babeldoc选项的情况。
本选项仅将后缀包含dual的文件切割拼接为中英文对照文件。
- 如果已有
dual文件，则对该dual附件右键-点击PDF2zh双语对照(双栏)
它会将翻译后的双栏PDF竖向切成两半，然后对裁剪后的单栏进行左右双语拼接。
得到后缀中包含compare的双语左右对照PDF文件。
选项四：PDF2zh：双语对照(单栏)
本选项适用于不启动babeldoc选项的情况。
本选项仅将后缀包含dual的文件切割拼接为中英文对照文件。
- 如果已有
dual文件，则对该dual附件右键-点击PDF2zh双语对照(单栏)
它会直接将翻译后的PDF进行左右双语拼接，不切割。
得到后缀中包含single-compare的双语左右对照PDF文件。
💡Tips
如果启用babeldoc，则生成的dual文件等效于双语对照（单栏）
-
自动启停：当您打开 Zotero 应用程序时，后台会自动启动 server.py 翻译服务；关闭 Zotero 时，服务也会被自动终止，释放系统资源。
-
稳定守护：在 Zotero 运行期间，如果 server.py 服务因任何原因意外崩溃，后台服务会检测到并在 10 秒内自动重启，确保服务的可用性。
-
静默通知：服务在启动、停止或翻译PDF时，都会通过macOS通知中心发送静默通知，让您能实时了解服务状态和翻译进度，而不会打扰您的工作流程。
-
右键翻译：在MacOS文件目录中右键文件翻译
贡献者@LinHuanli
- @Byaidu PDF2zh
- @windingwind zotero-plugin-template
欢迎提issue或者参与贡献
提issue前请先阅读本链接：常见问题
本项目交流QQ群: 971960014 入群验证回答: github
💐免费开源插件，您的支持是我继续开发的动力～
- SiliconFlow邀请链接: https://cloud.siliconflow.cn/i/WLYnNanQ
- 提供共享远程翻译服务（基于SealOS）
- 支持Obsidian式配置（不需要打开设置页面）
- 支持Zotero插件页面配置API Key
- 翻译进度显示
- 将翻译后的PDF转换为markdown或html
- 支持单栏左右对照和双栏左右对照
- 增加Drop Last功能，跳过引用文献不翻译
- 兼容babeldoc
- 支持远程部署
- 适配PolyglotPDF
- 完善Docker部署文档
- 加入插件市场
- 支持在zotero perference中设置pdf2zh参数