Zotero PDF2zh

在Zotero中使用PDF2zh和PDF2zh_next

当前版本信息： server.zip v4.0.4 | 插件 xpi v4.0.1

📚 项目文档： 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.

📖 目录

• 如何使用本插件
• 安装说明
• 第零步：安装Python和Zotero
• 第一步：安装uv/conda
• 第二步：下载项目文件
• 第三步：启动服务
• 第四步：下载并安装插件
• 第五步：Zotero端插件设置
• 第六步：关于翻译选项
• 第七步：关于包更新
• 其他安装方法
• 常见问题（FAQ）
• 关于网络
• 关于环境
• 关于翻译服务
• 关于OCR/扫描件
• 关于翻译效果
• 关于插件功能
• 关于提问
• 关于支持本插件
• 致谢
• 贡献者
• 如何支持我
• 开源协议与使用声明

---

如何使用本插件

本指南将引导您完成 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
  • 入群问题答案: github

安装说明

第零步：安装Python和Zotero

• Python：下载链接，建议安装 3.12 版本

• Zotero：支持 Zotero 7 和 Zotero 8（适配 by @Aphcity）

• 打开命令行工具（后续步骤都在命令行中执行）：

• Windows：按 Win + R → 输入 cmd → 回车（建议以管理员身份运行）
• macOS：按 Cmd + 空格 → 输入"终端" → 回车
• Linux：Ctrl + Alt + T

第一步：安装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文件夹
# 如果server.zip下载失败, 可以直接访问: https://github.com/guaguastandup/zotero-pdf2zh/blob/main/server.zip 手动下载
wget https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/refs/heads/main/server.zip
unzip server.zip

# 3. 进入server文件夹
cd server

💡 提示：确认目录结构

解压后，请确认您的目录结构应该是： zotero-pdf2zh/ └── server/ ├── server.py ├── ... └── requirements.txt

如果您看到的是 server/server/ 这样的嵌套结构（两层 server），说明解压出现了嵌套问题，请执行：

```shell

回到上级目录

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：

参数	说明	默认值
--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 文件夹。

第四步：下载并安装插件

新版本v4.0.1下载链接

1. 安装方式：在zotero中打开“工具-插件”，将xpi文件拖入，进行安装。（若拖入后功能未生效，请重启Zotero）
2. 如何更新：您可以在zotero中检查更新，或选择自动更新，来获取最新版本插件。

第五步：Zotero端插件设置

zotero 插件设置页面

检查服务器连接

在插件设置页面中，点击"Python Server IP"输入框旁边的"检查连接"按钮，可测试与Python服务的连接状态。若显示连接成功，则服务正常运行；若显示连接失败，请检查：

• server.py 脚本是否正在运行
• 端口号是否正确（默认8890）
• 防火墙/杀毒软件是否阻止了连接

配置选项说明

• 切换翻译引擎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文件中的字段相同(例如在pdf2zh_next中, openai对应的额外配置: openai_temperature和openai_send_temperature与config.toml文件中的字段相对应), 本功能将在未来继续优化, 可参考文档

网页端查看翻译进度

服务启动后，可在浏览器中访问 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.此服务可能会存在漏翻译的情况，如果需要高质量翻译请优先选择其他服务

1. 此服务仅支持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等后缀，请删除。

3. 此服务免费版支持的线程数较低，建议设置为6左右 | | 具有优惠/赠送的翻译服务 | zhipu | 智谱部分模型可支持免费调用 | 免费服务的并发数不要设置过高，建议设置为6以内 | | 高质量服务 | aliyunDashScope | 翻译效果较好，新用户有赠送额度，可以尝试 | 选择LLM API配置管理中的默认模型选项 | | 高质量服务 | deepseek（推荐） | 翻译效果好，有缓存命中机制 | 使用deepseek v3服务即可 |

4. 除了免费服务，您均需要配置自己的API Key和URL才可以使用翻译服务（某些服务不需要配置URL，可以忽略）

5. 您可以根据实际情况自行调整并发数

6. 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

3. 选择"Dual文件翻译页在前"可以交换生成顺序

4. 此选项等同于翻译引擎为pdf2zh_next, 且双语(Dual)文件显示模式为Left&Right时生成的文件 | | | 双语对照(裁剪) (crop-compare PDF) | 此选项仅针对双栏PDF论文。它会先将PDF竖向裁剪为单栏文件，再左右拼接。 | |

您可以多选条目，右键菜单，然后进行批量PDF翻译

第七步: 关于包更新

zotero插件和server脚本均具有自动更新功能, 但是为了使用最新版本babeldoc和pdf2zh_next, 您需要进行下列操作:

1. 进入server文件夹

2. 进入虚拟环境: 名称为zotero-pdf2zh-next-venv

# conda
conda activate zotero-pdf2zh-next-venv

# uv
## MacOS/Linux
source ./zotero-pdf2zh-venv-next/bin/activate
## Windows
.\zotero-pdf2zh-next-venv\Scripts\activate

1. 更新

# conda
pip install --upgrade pdf2zh_next babeldoc
# uv
uv pip install --upgrade pdf2zh_next babeldoc

其他安装方法

Windows exe 版本安装（仅限Windows用户）

如果您不想配置Python虚拟环境，可以直接使用pdf2zh_next 提供的预编译exe版本。

安装步骤：

1. 下载exe包：访问 pdf2zh_next Release 页面，下载 pdf2zh-v2.x.x-BabelDOC-v0.x.x-win64.zip（选择 with-assets 版本）

2. 解压文件：将下载的zip文件解压到 server 目录下，

3. 解压后目录结构：`server/pdf2zh-v2.x.x-BabelDOC-v0.x.x-win64/pdf2zh/pdf2z