guaguastandup/zotero-pdf2zh

PDF2zh for Zotero | Zotero PDF中文翻译插件

6,037

stars

625

commits

Python

primary language

Aug 27, 2026

updated

README

Zotero PDF2zh

Zotero PDF2zh

zotero target version zotero target version zotero target version zotero target version

Using Zotero Plugin Template

Downloads release License zread

在 Zotero 中直接使用 PDF2zhPDF2zh_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
    • 入群口令请到本仓库 GitHub / Gitee 页面的仓库简介(About)中查看,不要使用非官方搬运版中的口令
  • 📢 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

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

  • Zotero:支持 Zotero 7、Zotero 8、Zotero 9和Zotero 10,如无意外插件会持续支持最新版本,如果Zotero内自动更新失败,请下载最新插件文件重新安装尝试。

  • 打开命令行工具(后续步骤都在命令行中执行):

    • Windows:按 Win + R → 输入 cmd → 回车(建议以管理员身份运行
    • macOS:按 Cmd + 空格 → 输入"终端" → 回车
    • LinuxCtrl + 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文件夹
# 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

参数说明默认值
--hostServer 监听地址;默认仅本机访问,远程部署时才使用 0.0.0.0127.0.0.1
--port服务端口号8890
--check_update启动时检查更新True
--update_source优先更新源(github / gitee)。会两个都试,失败自动换另一个gitee
--enable_mirror启用 pip 镜像加速True
--mirror_source自定义镜像源 URLhttps://mirrors.ustc.edu.cn/pypi/simple
--enable_winexe使用 Windows exe 模式(需配合 --winexe_pathFalse

注意事项

  • 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 下载链接

  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 文件中的字段相同。v4.1.7 起,在「LLM API配置管理」里点「添加参数」,可从当前服务支持的字段下拉选择(也可选「自定义」手填)。OpenAI / DeepSeek / SiliconFlow 等支持 *_enable_json_mode(如 openai_enable_json_modedeepseek_enable_json_mode),默认关闭;部分模型漏译段落时可尝试设为 true。字段说明见 额外参数文档extraData.md

网页端查看翻译进度

服务启动后,可在浏览器中访问 http://127.0.0.1:8890 查看翻译进度和使用相关功能:


查看当前配置信息

实时查看翻译进度

查看历史翻译记录并预览下载

功能说明:

  • 查看当前server端的配置信息
  • 实时显示当前翻译任务状态
  • 查看翻译历史记录,支持预览和下载翻译后的文件

📢: v4.0.3(3月7日) windows端暂时不支持多进度条显示(多个pdf同时翻译时只会有一个进度条会更新,是bug待修复)

翻译引擎对比

插件支持两种翻译引擎,请根据需求选择:

对比项PDF2ZH (旧版)PDF2ZH Next (新版)
维护状态❌ 不再活跃维护✅ 持续更新维护
翻译速度⚡ 较快速度适中
自定义字体✅ 支持更换自定义字体❌ 不支持
配置文件config.jsonconfig.toml
双语模式默认为Top&Bottom默认为 Left&Right
术语表功能❌ 不支持✅ 自动提取并使用术语表
表格翻译❌ 不支持✅ 支持表格内容翻译
OCR兼容❌ 不支持✅ 支持 OCR 兼容模式和自动 OCR
支持的翻译服务支持海量翻译服务提供免费 siliconflowfree
上游项目Byaidu/PDFMathTranslatePDFMathTranslate-next

翻译服务配置

配置翻译服务需完成两步:

第一步:添加API配置

在"LLM API配置管理"区域点击"新增",填写服务配置信息。同一服务可添加多个配置,但只能激活其中一个。

第二步:选择翻译服务

在页面顶部的"翻译服务"下拉菜单中,选择要使用的服务名称。

警告:仅添加API配置不会生效,必须完成第二步选择服务,翻译功能才能使用。

💡 翻译服务介绍(必读)

服务类型服务名称服务介绍💡注意事项
免费&免配置的翻译服务siliconflowfree基于硅基流动提供的GLM4-9B模型, 仅支持翻译引擎pdf2zh_next,由@硅基流动@pdf2zh_next@BabelDOC联合提供服务1. 此服务无需选择qps,默认为20
2.此服务可能会存在漏翻译的情况,如果需要高质量翻译请优先选择其他服务
3. 此服务仅支持pdf2zh_next引擎
免费&免配置的翻译服务bing/googlebing/google的官方机器翻译bing和goole的翻译服务都存在限流,如果翻译失败,请将并发数设置调至2及以下重试
具有优惠/赠送的翻译服务openaliked加入火山引擎协作计划,个人用户每个模型每天最多赠送50w token1. 协作计划的额度赠送规则是:按照前一天参加协作的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插件设置端所选择的默认生成文件image3
裁剪PDF (crop PDF)选择dual/mono类型附件, 将会对选择的附件在宽度1/2处裁剪, 然后上下拼接, 此功能适合手机阅读
注意事项:
1. 本选项会将页面两侧空白处进行裁剪
2. 若产生截断了原文内容的情况, 可将server/utils/config.py中的config.pdf_w_offset值降低
image4
双语对照 (compare PDF)点击此选项, 会生成左边为原文, 右边为翻译后文本的PDF
1. 选择"Dual文件翻译页在前"可以交换生成顺序
2. 此选项等同于翻译引擎为pdf2zh_next, 且双语(Dual)文件显示模式Left&Right时生成的文件
image4
双语对照(裁剪) (crop-compare PDF)此选项仅针对双栏PDF论文。它会先将PDF竖向裁剪为单栏文件,再左右拼接。image4

您可以多选条目,右键菜单,然后进行批量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版本。

安装步骤:

  1. 下载exe包:访问 pdf2zh_next Release 页面,下载 pdf2zh-v2.x.x-BabelDOC-v0.x.x-win64.zip(选择 with-assets 版本)

  2. 解压文件:将下载的zip文件解压到 server 目录下,

  • 解压后目录结构:server/pdf2zh-v2.x.x-BabelDOC-v0.x.x-win64/pdf2zh/pdf2zh.exe
  1. 运行服务:
python server.py --enable_winexe=True --winexe_path='./pdf2zh-v2.x.x-BabelDOC-v0.x.x-win64/pdf2zh/pdf2zh.exe'

注意事项:

  • exe版本不需要配置Python虚拟环境,- 确保exe路径正确,路径相对于 server 目录
  • 如果遇到DLL相关错误,请安装 Visual C++ Redistributable
  • 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 用户 - 创建桌面快捷脚本:

  1. 先在当前终端输入 cd 命令查看完整路径
cd

终端会显示类似:D:\zotero-pdf2zh\server 的路径

  1. 在桌面新建一个文本文件,右键编辑,写入以下内容:
@echo off
cd /d <粘贴刚才复制的路径>
uv run --python 3.12 --with-requirements requirements.txt server.py
pause
  1. <粘贴刚才复制的路径> 替换为您复制的实际路径

  2. 重命名为 start-pdf2zh.bat(后缀名必须是 .bat

  3. 保存后双击即可启动

macOS / Linux 用户 - 配置别名(alias):

  1. 打开终端,编辑 shell 配置文件:
# 如果使用 zsh(macOS 默认)
nano ~/.zshrc
# 如果使用 bash
nano ~/.bashrc
  1. 在文件末尾添加别名(请根据实际路径修改):
alias pdf2zh-start='cd /path/to/zotero-pdf2zh/server && uv run --python 3.12 --with-requirements requirements.txt server.py'
  1. 保存后执行:
source ~/.zshrc
# 或
source ~/.bashrc
  1. 之后只需在终端输入 pdf2zh-start 即可一键启动

方式二:使用 conda 的用户

Windows 用户 - 创建桌面快捷脚本:

  1. 先在当前终端输入 cd 命令查看完整路径
cd

终端会显示类似:D:\zotero-pdf2zh\server 的路径

  1. 在桌面新建一个文本文件,右键编辑,写入以下内容:
@echo off
cd /d <粘贴刚才复制的路径>
python server.py --env_tool=conda
pause
  1. <粘贴刚才复制的路径> 替换为您复制的实际路径

  2. 重命名为 start-pdf2zh-conda.bat(后缀名必须是 .bat

  3. 保存后双击即可启动

macOS / Linux 用户 - 配置别名(alias):

  1. 打开终端,编辑 shell 配置文件:
# 如果使用 zsh(macOS 默认)
nano ~/.zshrc
# 如果使用 bash
nano ~/.bashrc
  1. 在文件末尾添加别名(请根据实际路径修改):
alias pdf2zh-start='cd /path/to/zotero-pdf2zh/server && python server.py --env_tool=conda'

💡 注意:使用此别名前,请确保已初始化 conda(通常在安装 conda 后会自动添加到 .bashrc.zshrc 中)

  1. 保存后执行:
source ~/.zshrc
# 或
source ~/.bashrc
  1. 之后只需在终端输入 pdf2zh-start 即可一键启动

常见问题(FAQ)

关于网络

  • 【🔥高频问题】Q:我遇到了网络问题(NetworkError when attempting to fetch resource),该怎么办?

  • A:

    • 首先点击插件设置页面中"Python Server IP"旁边的"检查连接"按钮,查看连接状态
    • 若显示连接失败,请按以下步骤排查:
      • 确保插件是最新版:版本号 4.1.x,而不是旧版本 3.0.x 或 2.4.3
      • 翻译过程中需要保证server.py脚本开启
      • 请检查8890端口是否被其他程序占用
      • 切换端口重试(可以多次尝试更换新的端口)
        • 切换端口需要修改两个地方(以新端口号为9999为例)
          • zotero插件配置里的python server ip里的8890修改为9999
          • 执行脚本时的指令修改为:python server.py --port=9999
      • 检查防火墙是否开启
      • 关闭杀毒软件并重启电脑
    • 另外如果您执行翻译时,终端有日志输出/正在尝试翻译,此后报网络错误,则不符合上述情况,应该优先解决终端中提示的报错。
  • 【🔥高频问题】Q: 翻译卡在某个地方不动了 / pdf2zh_next第一次翻译时进度条一直卡在某一处(例如10/100)/ 出现assets download failed问题

  • A:

    • 这是因为pdf2zh_next在首次启动时,需要远程下载字体和模型文件,这个过程比较慢。
    • 您可以:
      • 访问pdf2zh_next的最新release: https://github.com/PDFMathTranslate-next/PDFMathTranslate-next/releases, 下载其中的exe包,例如:pdf2zh-v2.6.4-BabelDOC-xxx-with-assets-win64.zip
        • 如果由于网络问题无法下载, 请加入QQ群下载群文件
      • 解压后打开其中的pdf2zh.exe,然后打开命令行中提示的gui路径(http://127.0.0.1:7860/),翻译一篇文章后退出。
      • 回到插件重新翻译。

    为什么这样做是有效的:

    • 资源已下载并加入缓存:通过exe包完成一次翻译后,字体和模型文件会被下载并缓存到系统中。之后再次使用插件时,就可以直接使用缓存的资源,无需重新下载。
    • 网络环境检查:如果依然出现下载失败的情况,请检查您的网络环境是否能够正常访问GitHub或相关资源服务器。您可以尝试切换网络、使用代理工具,或者加入QQ群下载群文件中的离线资源包。

关于环境

  • 【🔥高频问题】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方法在安装配置后不可以修改路径名/移动文件夹。

关于翻译服务

  • Q:我没配置API,可以用吗?

  • A:不可以,除非您使用的是免费的服务。

    • 例如,如果您选择pdf2zh_next引擎,并且使用siliconflowfree服务,就可以获得免费的服务,但是本服务可能会漏翻译一些内容。建议您优先自己配置API。
  • 【🔥高频问题】Q:我正在使用bing/google,也是免费的,但是翻译到一半就报错了/卡住了/中止了

  • A:

    • 因为bing/google的限流较为严重,您需要把线程数设置得非常低。

    • 建议您最好换到更加稳定的服务,以便长期使用。

  • Q:我感觉这个翻译消耗的Token很多,怎么办?

  • A:

    • 通常一篇10页的英文文献消耗Token量在7~10w左右,单页在5k左右,您可以先基于此数据进行检查
    • 如果您正在使用pdf2zh_next引擎,可以在zotero插件配置中,选择“禁用自动术语提取”。
  • 【🔥高频问题】Q:翻译后部分段落缺失(未被翻译),该怎么办?

  • A:

    • 原因说明:为了保证PDF能够正常生成,当翻译失败时,程序会使用原文替代翻译后的位置,因此会出现部分段落未翻译的情况。
    • 解决方法
      1. 尝试更换翻译引擎(pdf2zh/pdf2zh_next)
      2. 检查您的API是否超限(查看终端报错信息或API服务商后台)
      3. 如果使用的是免费服务(如bing/google),可能是限流导致,建议切换到更稳定的服务

关于OCR/扫描件

  • 【🔥高频问题】Q1:翻译界面提示 Scanned PDF detected, 翻译失败

  • A:

    • pdf2zh和pdf2zh_next不直接提供文档OCR功能, 您需要用其他工具对自己的扫描版文件进行OCR处理, 再调用插件的翻译功能。
    • 推荐使用 Adobe Acrobat Pro、ABBYY FineReader 或其他OCR工具对扫描版PDF进行文字识别处理,然后再使用本插件进行翻译。
  • Q2:pdf2zh_next服务中的ocr模式与兼容模式是指什么?

  • A:

    • OCR选项并不是直接提供OCR服务的,它只是一个对于OCR后的文件进行兼容的临时方案,您保持自动开启OCR临时方案的选项开启即可。
    • 兼容模式生成的文件大小会更大,您在非必要的时候不需要开启。(如果您翻译功能正常,但是某一次失败了/并且确定不是远程翻译服务的问题,那您可以尝试开启)

关于翻译效果

  • Q:为什么会出现段落缺失、断行或重影的情况?
  • A:
    • 扫描件问题:如果文档本身是扫描件,必须先经过OCR处理后再进行翻译。若未进行OCR识别,会导致断行或段落缺失问题。
    • 重影现象:出现的重影通常是由于OCR识别不准确或PDF文件本身的问题导致的。建议使用高质量的OCR工具重新处理文档。
    • 段落缺失:如前文所述,翻译失败时程序会用原文替代,建议先排查 API 服务是否正常。使用 pdf2zh_next 时,也可在 LLM 配置的额外参数里开启对应服务的 *_enable_json_mode(默认关闭),例如 openai_enable_json_modedeepseek_enable_json_mode

关于插件功能

  • Q:我不知道zotero插件里的各个功能是什么意思
  • A:您可以自由尝试,请尽量不要对这些问题进行提问,翻译引擎具有缓存的设置,也就是说您重复对同一篇文献进行翻译时,可能不会消耗过多的Token(不能保证完全不消耗)

关于提问

提问前请先尝试以下方法:

  • 将终端报错信息发送给AI(ChatGPT、Gemini、DeepSeek等)进行分析
  • 在本文档中搜索错误关键词或查阅相关章节

如需在群内提问,请提供:

  • 终端完整输出(复制到txt文件)

  • Zotero设置截图

  • Zotero弹窗截图

  • 说明您已尝试过的解决方法

  • Q:我在群里问问题,怎么没人回复我?

  • A:

    • 请确认您的问题不属于常见问题,或在问题描述中说明"已查阅常见问题但仍未解决"
    • 请提供终端输出、Zotero设置截图和弹窗截图,以便定位问题
    • 如果被漏看,可以稍后重新发或@群主
  • Q:可是我给作者打赏了,希望能得到优先支持。

  • A:非常感谢您的支持!打赏是对项目的肯定和鼓励,如果打赏后遇到问题,欢迎私聊群主,我会尽力协助您解决。

关于支持本插件

  • Q:我很喜欢这个插件,想要提供支持,让这个插件更好地长期运行,我该怎么做?
  • A:
    • 您可以继续下滑,找到支持本项目开发者的方式(支付码/爱发电等方式,您的昵称将出现在赞助者名单)
    • 您可以参与本项目的开发
    • 您可以为本项目点一个star
    • 您可以在issue区提出您期望的未来功能(需是合理的功能建议)
    • 您可以将本插件推荐给身边的朋友,并且在他们的安装过程中给出一些指导

致谢

贡献者

📢: 桌面端构建中(Coming Soon!),改动较大,有新的功能&修复了旧bug,暂不接收新的Pull Request

感谢各位贡献者对项目的付出!!

贡献者名单

guaguastandup Aphcity Bocheng-L htyxyt Rosetears520 taozhe6 Norhua KANIKIG Snowflake-Pink LinHuanli chunzhimoe tcpsoftware

如何支持我

💐 免费开源插件,您的支持是我继续开发的动力~祝您科研/工作/学习顺利!

  • 赞助时, 请在备注中留下您希望出现在赞助者名单的姓名或昵称💗

  • ☕️ Wechat微信/Alipay支付宝

  • 🐳 爱发电

  • 🤖 【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

  • 赞助者名单(持续更新), 按照时间先后排序:

    • 我会定期重复检查,但如果仍然有统计遗漏, 请您联系我, QQ: 546409178
    • 如果您希望在赞助者名单中补充您的昵称和您的个人主页链接,也请联系我~

赞助者名单

感谢您的支持! 您的支持是我开发的动力~


awwaawwa htyxyt jiajia bibiu77 *琰 *冬萍 阿赟 *声 h*u 爱发电用户 soooda 泪花花 狐狸 山间火 Angus 研究所 Henrietta 匿名 柿十 *川 Milse n*r *糖 小马 **龙 *u prprprprpprpr Lstar *头 YoungEmperorCaesar Yuriart J*h GeorgeXiaobinRen Keeptg h*o C*u 莫林 *萌 *川 *博 Sine璇 🐑H-Yang独角兽先生 *洋 kylinduu 南方嘉木
感谢

Star History

star-history-2026813 (1).png

开源协议与使用声明

本项目采用开源协议发布,所有开发者在使用本插件代码时必须遵循以下原则:

  1. 遵守开源协议:使用本项目的代码必须遵循本项目所采用的AGPL开源协议(详见 LICENSE 文件),包括但不限于保留版权声明、开源修改后的代码等。

  2. 禁止商业倒卖:本插件为免费开源项目,严禁任何形式的商业倒卖行为,包括但不限于:

    • 将本插件打包后以收费形式出售
    • 以"代安装"、"技术服务"等名义收取高额费用后交付本插件
    • 将本插件作为付费产品的一部分进行销售

    ⚠️ 特别提醒:商业贩子请勿加入QQ群提问,不要消耗维护者的精力。一旦发现,将直接移出群聊并拉黑。

  3. 合理使用:欢迎个人学习、研究、非商业用途的使用。如需商业使用,请联系作者获取授权。

  4. 尊重开源精神:我们鼓励开发者基于本项目进行改进和贡献,但请尊重原作者的劳动成果,遵守开源社区的基本准则。

如发现违反上述原则的行为,作者保留追究法律责任的权利。

Contributors

guaguastandup

557 commits

chunzhimoe

21 commits

taozhe6

15 commits

Rosetears520

14 commits

guaguastandup/zotero-pdf2zh

PDF2zh for Zotero | Zotero PDF中文翻译插件

6,037

stars

625

commits

Python

primary language

Aug 27, 2026

updated

README

Zotero PDF2zh

Zotero PDF2zh

zotero target version zotero target version zotero target version zotero target version

Using Zotero Plugin Template

Downloads release License zread

在 Zotero 中直接使用 PDF2zhPDF2zh_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
    • 入群口令请到本仓库 GitHub / Gitee 页面的仓库简介(About)中查看,不要使用非官方搬运版中的口令
  • 📢 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

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

  • Zotero:支持 Zotero 7、Zotero 8、Zotero 9和Zotero 10,如无意外插件会持续支持最新版本,如果Zotero内自动更新失败,请下载最新插件文件重新安装尝试。

  • 打开命令行工具(后续步骤都在命令行中执行):

    • Windows:按 Win + R → 输入 cmd → 回车(建议以管理员身份运行
    • macOS:按 Cmd + 空格 → 输入"终端" → 回车
    • LinuxCtrl + 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文件夹
# 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

参数说明默认值
--hostServer 监听地址;默认仅本机访问,远程部署时才使用 0.0.0.0127.0.0.1
--port服务端口号8890
--check_update启动时检查更新True
--update_source优先更新源(github / gitee)。会两个都试,失败自动换另一个gitee
--enable_mirror启用 pip 镜像加速True
--mirror_source自定义镜像源 URLhttps://mirrors.ustc.edu.cn/pypi/simple
--enable_winexe使用 Windows exe 模式(需配合 --winexe_pathFalse

注意事项

  • 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 下载链接

  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 文件中的字段相同。v4.1.7 起,在「LLM API配置管理」里点「添加参数」,可从当前服务支持的字段下拉选择(也可选「自定义」手填)。OpenAI / DeepSeek / SiliconFlow 等支持 *_enable_json_mode(如 openai_enable_json_modedeepseek_enable_json_mode),默认关闭;部分模型漏译段落时可尝试设为 true。字段说明见 额外参数文档extraData.md

网页端查看翻译进度

服务启动后,可在浏览器中访问 http://127.0.0.1:8890 查看翻译进度和使用相关功能:


查看当前配置信息

实时查看翻译进度

查看历史翻译记录并预览下载

功能说明:

  • 查看当前server端的配置信息
  • 实时显示当前翻译任务状态
  • 查看翻译历史记录,支持预览和下载翻译后的文件

📢: v4.0.3(3月7日) windows端暂时不支持多进度条显示(多个pdf同时翻译时只会有一个进度条会更新,是bug待修复)

翻译引擎对比

插件支持两种翻译引擎,请根据需求选择:

对比项PDF2ZH (旧版)PDF2ZH Next (新版)
维护状态❌ 不再活跃维护✅ 持续更新维护
翻译速度⚡ 较快速度适中
自定义字体✅ 支持更换自定义字体❌ 不支持
配置文件config.jsonconfig.toml
双语模式默认为Top&Bottom默认为 Left&Right
术语表功能❌ 不支持✅ 自动提取并使用术语表
表格翻译❌ 不支持✅ 支持表格内容翻译
OCR兼容❌ 不支持✅ 支持 OCR 兼容模式和自动 OCR
支持的翻译服务支持海量翻译服务提供免费 siliconflowfree
上游项目Byaidu/PDFMathTranslatePDFMathTranslate-next

翻译服务配置

配置翻译服务需完成两步:

第一步:添加API配置

在"LLM API配置管理"区域点击"新增",填写服务配置信息。同一服务可添加多个配置,但只能激活其中一个。

第二步:选择翻译服务

在页面顶部的"翻译服务"下拉菜单中,选择要使用的服务名称。

警告:仅添加API配置不会生效,必须完成第二步选择服务,翻译功能才能使用。

💡 翻译服务介绍(必读)

服务类型服务名称服务介绍💡注意事项
免费&免配置的翻译服务siliconflowfree基于硅基流动提供的GLM4-9B模型, 仅支持翻译引擎pdf2zh_next,由@硅基流动@pdf2zh_next@BabelDOC联合提供服务1. 此服务无需选择qps,默认为20
2.此服务可能会存在漏翻译的情况,如果需要高质量翻译请优先选择其他服务
3. 此服务仅支持pdf2zh_next引擎
免费&免配置的翻译服务bing/googlebing/google的官方机器翻译bing和goole的翻译服务都存在限流,如果翻译失败,请将并发数设置调至2及以下重试
具有优惠/赠送的翻译服务openaliked加入火山引擎协作计划,个人用户每个模型每天最多赠送50w token1. 协作计划的额度赠送规则是:按照前一天参加协作的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插件设置端所选择的默认生成文件image3
裁剪PDF (crop PDF)选择dual/mono类型附件, 将会对选择的附件在宽度1/2处裁剪, 然后上下拼接, 此功能适合手机阅读
注意事项:
1. 本选项会将页面两侧空白处进行裁剪
2. 若产生截断了原文内容的情况, 可将server/utils/config.py中的config.pdf_w_offset值降低
image4
双语对照 (compare PDF)点击此选项, 会生成左边为原文, 右边为翻译后文本的PDF
1. 选择"Dual文件翻译页在前"可以交换生成顺序
2. 此选项等同于翻译引擎为pdf2zh_next, 且双语(Dual)文件显示模式Left&Right时生成的文件
image4
双语对照(裁剪) (crop-compare PDF)此选项仅针对双栏PDF论文。它会先将PDF竖向裁剪为单栏文件,再左右拼接。image4

您可以多选条目,右键菜单,然后进行批量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版本。

安装步骤:

  1. 下载exe包:访问 pdf2zh_next Release 页面,下载 pdf2zh-v2.x.x-BabelDOC-v0.x.x-win64.zip(选择 with-assets 版本)

  2. 解压文件:将下载的zip文件解压到 server 目录下,

  • 解压后目录结构:server/pdf2zh-v2.x.x-BabelDOC-v0.x.x-win64/pdf2zh/pdf2zh.exe
  1. 运行服务:
python server.py --enable_winexe=True --winexe_path='./pdf2zh-v2.x.x-BabelDOC-v0.x.x-win64/pdf2zh/pdf2zh.exe'

注意事项:

  • exe版本不需要配置Python虚拟环境,- 确保exe路径正确,路径相对于 server 目录
  • 如果遇到DLL相关错误,请安装 Visual C++ Redistributable
  • 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 用户 - 创建桌面快捷脚本:

  1. 先在当前终端输入 cd 命令查看完整路径
cd

终端会显示类似:D:\zotero-pdf2zh\server 的路径

  1. 在桌面新建一个文本文件,右键编辑,写入以下内容:
@echo off
cd /d <粘贴刚才复制的路径>
uv run --python 3.12 --with-requirements requirements.txt server.py
pause
  1. <粘贴刚才复制的路径> 替换为您复制的实际路径

  2. 重命名为 start-pdf2zh.bat(后缀名必须是 .bat

  3. 保存后双击即可启动

macOS / Linux 用户 - 配置别名(alias):

  1. 打开终端,编辑 shell 配置文件:
# 如果使用 zsh(macOS 默认)
nano ~/.zshrc
# 如果使用 bash
nano ~/.bashrc
  1. 在文件末尾添加别名(请根据实际路径修改):
alias pdf2zh-start='cd /path/to/zotero-pdf2zh/server && uv run --python 3.12 --with-requirements requirements.txt server.py'
  1. 保存后执行:
source ~/.zshrc
# 或
source ~/.bashrc
  1. 之后只需在终端输入 pdf2zh-start 即可一键启动

方式二:使用 conda 的用户

Windows 用户 - 创建桌面快捷脚本:

  1. 先在当前终端输入 cd 命令查看完整路径
cd

终端会显示类似:D:\zotero-pdf2zh\server 的路径

  1. 在桌面新建一个文本文件,右键编辑,写入以下内容:
@echo off
cd /d <粘贴刚才复制的路径>
python server.py --env_tool=conda
pause
  1. <粘贴刚才复制的路径> 替换为您复制的实际路径

  2. 重命名为 start-pdf2zh-conda.bat(后缀名必须是 .bat

  3. 保存后双击即可启动

macOS / Linux 用户 - 配置别名(alias):

  1. 打开终端,编辑 shell 配置文件:
# 如果使用 zsh(macOS 默认)
nano ~/.zshrc
# 如果使用 bash
nano ~/.bashrc
  1. 在文件末尾添加别名(请根据实际路径修改):
alias pdf2zh-start='cd /path/to/zotero-pdf2zh/server && python server.py --env_tool=conda'

💡 注意:使用此别名前,请确保已初始化 conda(通常在安装 conda 后会自动添加到 .bashrc.zshrc 中)

  1. 保存后执行:
source ~/.zshrc
# 或
source ~/.bashrc
  1. 之后只需在终端输入 pdf2zh-start 即可一键启动

常见问题(FAQ)

关于网络

  • 【🔥高频问题】Q:我遇到了网络问题(NetworkError when attempting to fetch resource),该怎么办?

  • A:

    • 首先点击插件设置页面中"Python Server IP"旁边的"检查连接"按钮,查看连接状态
    • 若显示连接失败,请按以下步骤排查:
      • 确保插件是最新版:版本号 4.1.x,而不是旧版本 3.0.x 或 2.4.3
      • 翻译过程中需要保证server.py脚本开启
      • 请检查8890端口是否被其他程序占用
      • 切换端口重试(可以多次尝试更换新的端口)
        • 切换端口需要修改两个地方(以新端口号为9999为例)
          • zotero插件配置里的python server ip里的8890修改为9999
          • 执行脚本时的指令修改为:python server.py --port=9999
      • 检查防火墙是否开启
      • 关闭杀毒软件并重启电脑
    • 另外如果您执行翻译时,终端有日志输出/正在尝试翻译,此后报网络错误,则不符合上述情况,应该优先解决终端中提示的报错。
  • 【🔥高频问题】Q: 翻译卡在某个地方不动了 / pdf2zh_next第一次翻译时进度条一直卡在某一处(例如10/100)/ 出现assets download failed问题

  • A:

    • 这是因为pdf2zh_next在首次启动时,需要远程下载字体和模型文件,这个过程比较慢。
    • 您可以:
      • 访问pdf2zh_next的最新release: https://github.com/PDFMathTranslate-next/PDFMathTranslate-next/releases, 下载其中的exe包,例如:pdf2zh-v2.6.4-BabelDOC-xxx-with-assets-win64.zip
        • 如果由于网络问题无法下载, 请加入QQ群下载群文件
      • 解压后打开其中的pdf2zh.exe,然后打开命令行中提示的gui路径(http://127.0.0.1:7860/),翻译一篇文章后退出。
      • 回到插件重新翻译。

    为什么这样做是有效的:

    • 资源已下载并加入缓存:通过exe包完成一次翻译后,字体和模型文件会被下载并缓存到系统中。之后再次使用插件时,就可以直接使用缓存的资源,无需重新下载。
    • 网络环境检查:如果依然出现下载失败的情况,请检查您的网络环境是否能够正常访问GitHub或相关资源服务器。您可以尝试切换网络、使用代理工具,或者加入QQ群下载群文件中的离线资源包。

关于环境

  • 【🔥高频问题】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方法在安装配置后不可以修改路径名/移动文件夹。

关于翻译服务

  • Q:我没配置API,可以用吗?

  • A:不可以,除非您使用的是免费的服务。

    • 例如,如果您选择pdf2zh_next引擎,并且使用siliconflowfree服务,就可以获得免费的服务,但是本服务可能会漏翻译一些内容。建议您优先自己配置API。
  • 【🔥高频问题】Q:我正在使用bing/google,也是免费的,但是翻译到一半就报错了/卡住了/中止了

  • A:

    • 因为bing/google的限流较为严重,您需要把线程数设置得非常低。

    • 建议您最好换到更加稳定的服务,以便长期使用。

  • Q:我感觉这个翻译消耗的Token很多,怎么办?

  • A:

    • 通常一篇10页的英文文献消耗Token量在7~10w左右,单页在5k左右,您可以先基于此数据进行检查
    • 如果您正在使用pdf2zh_next引擎,可以在zotero插件配置中,选择“禁用自动术语提取”。
  • 【🔥高频问题】Q:翻译后部分段落缺失(未被翻译),该怎么办?

  • A:

    • 原因说明:为了保证PDF能够正常生成,当翻译失败时,程序会使用原文替代翻译后的位置,因此会出现部分段落未翻译的情况。
    • 解决方法
      1. 尝试更换翻译引擎(pdf2zh/pdf2zh_next)
      2. 检查您的API是否超限(查看终端报错信息或API服务商后台)
      3. 如果使用的是免费服务(如bing/google),可能是限流导致,建议切换到更稳定的服务

关于OCR/扫描件

  • 【🔥高频问题】Q1:翻译界面提示 Scanned PDF detected, 翻译失败

  • A:

    • pdf2zh和pdf2zh_next不直接提供文档OCR功能, 您需要用其他工具对自己的扫描版文件进行OCR处理, 再调用插件的翻译功能。
    • 推荐使用 Adobe Acrobat Pro、ABBYY FineReader 或其他OCR工具对扫描版PDF进行文字识别处理,然后再使用本插件进行翻译。
  • Q2:pdf2zh_next服务中的ocr模式与兼容模式是指什么?

  • A:

    • OCR选项并不是直接提供OCR服务的,它只是一个对于OCR后的文件进行兼容的临时方案,您保持自动开启OCR临时方案的选项开启即可。
    • 兼容模式生成的文件大小会更大,您在非必要的时候不需要开启。(如果您翻译功能正常,但是某一次失败了/并且确定不是远程翻译服务的问题,那您可以尝试开启)

关于翻译效果

  • Q:为什么会出现段落缺失、断行或重影的情况?
  • A:
    • 扫描件问题:如果文档本身是扫描件,必须先经过OCR处理后再进行翻译。若未进行OCR识别,会导致断行或段落缺失问题。
    • 重影现象:出现的重影通常是由于OCR识别不准确或PDF文件本身的问题导致的。建议使用高质量的OCR工具重新处理文档。
    • 段落缺失:如前文所述,翻译失败时程序会用原文替代,建议先排查 API 服务是否正常。使用 pdf2zh_next 时,也可在 LLM 配置的额外参数里开启对应服务的 *_enable_json_mode(默认关闭),例如 openai_enable_json_modedeepseek_enable_json_mode

关于插件功能

  • Q:我不知道zotero插件里的各个功能是什么意思
  • A:您可以自由尝试,请尽量不要对这些问题进行提问,翻译引擎具有缓存的设置,也就是说您重复对同一篇文献进行翻译时,可能不会消耗过多的Token(不能保证完全不消耗)

关于提问

提问前请先尝试以下方法:

  • 将终端报错信息发送给AI(ChatGPT、Gemini、DeepSeek等)进行分析
  • 在本文档中搜索错误关键词或查阅相关章节

如需在群内提问,请提供:

  • 终端完整输出(复制到txt文件)

  • Zotero设置截图

  • Zotero弹窗截图

  • 说明您已尝试过的解决方法

  • Q:我在群里问问题,怎么没人回复我?

  • A:

    • 请确认您的问题不属于常见问题,或在问题描述中说明"已查阅常见问题但仍未解决"
    • 请提供终端输出、Zotero设置截图和弹窗截图,以便定位问题
    • 如果被漏看,可以稍后重新发或@群主
  • Q:可是我给作者打赏了,希望能得到优先支持。

  • A:非常感谢您的支持!打赏是对项目的肯定和鼓励,如果打赏后遇到问题,欢迎私聊群主,我会尽力协助您解决。

关于支持本插件

  • Q:我很喜欢这个插件,想要提供支持,让这个插件更好地长期运行,我该怎么做?
  • A:
    • 您可以继续下滑,找到支持本项目开发者的方式(支付码/爱发电等方式,您的昵称将出现在赞助者名单)
    • 您可以参与本项目的开发
    • 您可以为本项目点一个star
    • 您可以在issue区提出您期望的未来功能(需是合理的功能建议)
    • 您可以将本插件推荐给身边的朋友,并且在他们的安装过程中给出一些指导

致谢

贡献者

📢: 桌面端构建中(Coming Soon!),改动较大,有新的功能&修复了旧bug,暂不接收新的Pull Request

感谢各位贡献者对项目的付出!!

贡献者名单

guaguastandup Aphcity Bocheng-L htyxyt Rosetears520 taozhe6 Norhua KANIKIG Snowflake-Pink LinHuanli chunzhimoe tcpsoftware

如何支持我

💐 免费开源插件,您的支持是我继续开发的动力~祝您科研/工作/学习顺利!

  • 赞助时, 请在备注中留下您希望出现在赞助者名单的姓名或昵称💗

  • ☕️ Wechat微信/Alipay支付宝

  • 🐳 爱发电

  • 🤖 【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

  • 赞助者名单(持续更新), 按照时间先后排序:

    • 我会定期重复检查,但如果仍然有统计遗漏, 请您联系我, QQ: 546409178
    • 如果您希望在赞助者名单中补充您的昵称和您的个人主页链接,也请联系我~

赞助者名单

感谢您的支持! 您的支持是我开发的动力~


awwaawwa htyxyt jiajia bibiu77 *琰 *冬萍 阿赟 *声 h*u 爱发电用户 soooda 泪花花 狐狸 山间火 Angus 研究所 Henrietta 匿名 柿十 *川 Milse n*r *糖 小马 **龙 *u prprprprpprpr Lstar *头 YoungEmperorCaesar Yuriart J*h GeorgeXiaobinRen Keeptg h*o C*u 莫林 *萌 *川 *博 Sine璇 🐑H-Yang独角兽先生 *洋 kylinduu 南方嘉木
感谢

Star History

star-history-2026813 (1).png

开源协议与使用声明

本项目采用开源协议发布,所有开发者在使用本插件代码时必须遵循以下原则:

  1. 遵守开源协议:使用本项目的代码必须遵循本项目所采用的AGPL开源协议(详见 LICENSE 文件),包括但不限于保留版权声明、开源修改后的代码等。

  2. 禁止商业倒卖:本插件为免费开源项目,严禁任何形式的商业倒卖行为,包括但不限于:

    • 将本插件打包后以收费形式出售
    • 以"代安装"、"技术服务"等名义收取高额费用后交付本插件
    • 将本插件作为付费产品的一部分进行销售

    ⚠️ 特别提醒:商业贩子请勿加入QQ群提问,不要消耗维护者的精力。一旦发现,将直接移出群聊并拉黑。

  3. 合理使用:欢迎个人学习、研究、非商业用途的使用。如需商业使用,请联系作者获取授权。

  4. 尊重开源精神:我们鼓励开发者基于本项目进行改进和贡献,但请尊重原作者的劳动成果,遵守开源社区的基本准则。

如发现违反上述原则的行为,作者保留追究法律责任的权利。

Contributors

guaguastandup

557 commits

chunzhimoe

21 commits

taozhe6

15 commits

Rosetears520

14 commits

Languages

Python

53.8%

HTML

19.6%

TypeScript

14.3%

Shell

4.3%

JavaScript

2.2%

PowerShell

1.8%

Batchfile

1.7%

Fluent

1.5%