【Zotero-pdf2zh】快速搞定 PDF 翻译，完美保留原文格式

引言

在学术研究中，阅读外文文献是常态，而一款能在翻译时保留原文格式的工具则至关重要。PDFMathTranslate Next 借助 BabelDOC 翻译引擎，能轻松实现“结构保持 + 双语对照”的精准翻译，是处理科研文献的理想选择。

目前，Zotero + PDF2zh/PDF2zh_next 的组合已成为一条活跃且广受好评的实现路径。Zotero-pdf2zh 插件现已更新到更为简洁易用的 3.x 版本。接下来，本教程将引导你完成配置，并详细演示如何通过 Python和 Docker 这两种方式来部署翻译服务。

若您只想使用 pdf2zh_next 不使用zotero插件，可参考这篇教程：【PDF2zh 2.0】三种部署指南与 Zotero 插件配置 - 她笑中藏泪花
若觉得 Python 部署有难度，可直接看下方 Docker 方案；
若仍嫌麻烦，建议试用沉浸式翻译 BabelDOC 登陆账号拖入文件开始翻译

项目资源链接：
Zotero - PDF2zh 插件：guaguastandup/zotero-pdf2zh
PDF2zh_next：PDFMathTranslate/PDFMathTranslate-next

环境依赖

Python下载链接建议安装 Python 3.12。
- 个人安装教程（仅需安装Python即可，不用安装pycharm）：python和pycharm的下载和安装以及新建项目
插件目前支持 Zotero 7 桌面端，Zotero 8 待适配。Zotero官网下载链接
Docker（可选）：您可以从 Docker 官网下载。
- 个人安装教程：【Docker】告别环境配置噩梦：从零到一的安装指南
模型服务（OpenAI 兼容）：您需要一个大语言模型的 API Key 和 Base URL。
Zotero 插件下载：
zotero-pdf2zh：前往GitHub Releases 下载 .xpi（v3.x.x）在 Zotero 中 “工具 → 插件” 将 .xpi 拖入安装，必要时重启 Zotero；若未生效请重启 Zotero。

Part 1：Python部署

第一步: 安装uv

# 方法一（可选）：用 pip 安装 uv
pip install uv

# 方法二（推荐）：使用官方独立安装脚本
# macOS / Linux（任选其一）
curl -LsSf https://astral.sh/uv/install.sh | sh
# 或
wget -qO- https://astral.sh/uv/install.sh | sh

# Windows（PowerShell）
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

检查uv安装是否成功(必做)：

uv --version

若检查失败，多半是 PATH 未生效。将 uv 的安装目录加入 PATH 后重启终端：

# Windows PowerShell 
$env:Path = "$env:USERPROFILE\.local\bin;$env:Path"

# macOS / Linux
export PATH="$HOME/.local/bin:$PATH"

第二步: 下载并解压项目文件

Windows（CMD）

# 1. 创建并进入zotero-pdf2zh文件夹
mkdir zotero-pdf2zh && cd zotero-pdf2zh

# 2. 下载并解压server文件夹
# 如果server.zip下载失败, 可以直接访问: https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/server.zip 手动下载
curl -L -o server.zip https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/server.zip
REM 解压（任选一种；如命令行解压失败，可在资源管理器中右键解压到当前目录）
powershell -Command "Expand-Archive -Path '.\server.zip' -DestinationPath '.' -Force"
REM 或者（如果 tar 可用）
REM tar -xf server.zip

# 3. 进入server文件夹
cd server

Mac/Linux

# 1. 创建并进入zotero-pdf2zh文件夹
mkdir zotero-pdf2zh && cd zotero-pdf2zh

# 2. 下载并解压server文件夹
# 如果server.zip下载失败, 可以直接访问: https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/server.zip 手动下载
curl -L -o server.zip https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/server.zip
# 解压（任选其一）
unzip -o docker.zip -d .
# 或（若系统支持 bsdtar 解压 zip）
# tar -xf docker.zip

# 3. 进入server文件夹
cd server

解压后的server目录包括：

server.py
requirements.txt
config/
translated/
doc/
utils/

第三步: 安装依赖并启动服务

进入 server 目录后安装依赖：
```
pip install -r requirements.txt
```

启动服务（默认启用虚拟环境与端口 8890，可按需调整）：

python server.py
# 常用参数：
# --enable_venv=False       # 关闭虚拟环境托管（全局 Python 3.12 时可选）
# --env_tool=conda          # 将环境托管工具切换为 conda
# --port=8890               # 修改端口
# --check_update=False      # 关闭启动时的自动更新检查
#--enable_mirror=Flase      # 关闭包安装时启用镜像

使用pdf2zh_next的exe启动服务

python server.py --enable_winexe=True --winexe_path="Your\path\to\pdf2zh\pdf2zh.exe"

第四步：开始翻译

插件设置路径：编辑 → 首选项 → PDF2zh。在此可切换翻译引擎、配置 API 服务（Base URL、API Key、模型名等）与并发/QPS 参数。
随后在 Zotero 主界面选中文献，右键选择 “翻译/双语对照”等操作即可。

一键启动脚本

第一步：获取 `server.py` 的目录路径

先把终端/命令行打开到 server.py 所在的文件夹
- Windows：打开放有 server.py 的文件夹，在空白处按住 Shift 右键 → 在终端中打开（或地址栏输入 powershell/cmd 回车）。
- macOS：在 Finder 里打开该文件夹，右键空白处 → 服务 → 在文件夹位置打开新终端（没有的话，可先打开“终端”后用 cd 进入这个文件夹）。
- Linux：打开“终端”，用 cd 进入放有 server.py 的文件夹。
复制下面这一行回车执行（这行用的是 Python 自带的 pathlib 库，不需要 pip 安装）：
```
python -c "import pathlib; print(pathlib.Path('server.py').resolve().parent)"
```
- 如果你的电脑只有 python3 命令，把上面的 python 换成 python3。
- Windows 如果 python 不行，试试：
```
py -3 -c "import pathlib; print(pathlib.Path('server.py').resolve().parent)"
```
终端会输出一行目录路径，复制这行：
- Windows 例子：D:\work\myapp\server
- macOS/Linux 例子：/Users/you/work/myapp/server

请复制并保存好这行路径，我们马上就要用它！

第二步：选你的模板并复制

根据你的电脑系统，选择一个对应的模板。

如果你是 Windows 用户，请复制这个：

@echo off
chcp 65001 >nul
set PYTHONUTF8=1
rem ← 只需要修改下面这一行
set "PROJECT_PATH=这里替换成你的路径"
python "%PROJECT_PATH%\server.py"
pause

如果你是 macOS 或 Linux 用户，请复制这个：

#!/usr/bin/env bash
set -euo pipefail
export PYTHONUTF8=1
# ← 只需要修改下面这一行
PROJECT_PATH="这里替换成你的路径"
cd "$PROJECT_PATH"
python3 server.py
read -rp $'完成。按 Enter 退出…' _

若您能看懂该脚本，知道修改哪里，那么请直接到第四步。

第三步：让 AI 帮你生成脚本

现在，我们要请一位的 AI 助手DeepSeek来帮我们生成脚本。

先复制下面这段话：
你好，请你根据我提供的路径和这个模板，生成一个可以直接供我使用的自动化脚本，并告诉我怎么用。
紧接着，粘贴你在第一步获取的路径。
最后，粘贴你在第二步选择的对应模板。

把这三段内容组合在一起，像下面这个样子，然后一次性发给 AI：

发送给AI的完整示例：
你好，请你根据我提供的路径和这个模板，生成一个可以直接供我使用的自动化脚本，并告诉我怎么用。
我的路径是：D:\project\server
我的模板是：
@echo off
chcp 65001 >nul
set PYTHONUTF8=1
rem ← 只需要修改下面这一行
set "PROJECT_PATH=这里替换成你的路径"
python "%PROJECT_PATH%\server.py"
pause

AI 会非常聪明地帮你把路径填好，并生成最终的完美脚本代码。

第四步：运行脚本

AI 已经把最终的脚本代码给你了，现在我们只需要把它保存成一个可执行的文件。

对于 Windows 用户 (.bat 文件):

在电脑任意位置（比如桌面）右键，选择“新建” -> “文本文档”。
打开这个新建的文本文档，把你从 AI 那里复制来的最终代码粘贴进去。
点击左上角的“文件”，选择“另存为”。
在弹出的窗口中，最关键的一步：
- “保存类型”：一定要选择“所有文件 (*.*)”。
- “文件名”：给它取个名字，但后缀必须是 .bat。例如：一键启动.bat。
点击“保存”。现在，桌面上就出现了一个带齿轮图标的文件。

对于 macOS / Linux 用户 (.sh 文件):

打开“文本编辑” (TextEdit) 或任何文本编辑器。
把 AI 生成的最终代码粘贴进去。
- Mac 用户请注意：如果用的是“文本编辑”，请在菜单栏选择“格式” -> “制作纯文本”，确保是纯文本模式。
保存文件。给它取个名字，后缀必须是 .sh。例如：startup.sh，并将它保存在你喜欢的位置（比如桌面）。
最后一步，赋予它运行的权限。打开“终端”，输入 chmod +x （注意 +x 后面有个空格），然后把刚才保存的 .sh 文件从桌面拖到终端窗口里，最后按回车。

Part 2：Docker 部署（Compose）

如果你想使用 pdf2zh（1.x）作为翻译引擎，请直接跳到文末章节：“（可选）切换为 pdf2zh”。

第一步：确认 Docker 环境就绪

docker version
docker compose version

如果显示不了 docker compose，你可能安装的是老版 docker-compose，后续命令把 docker compose 换成 docker-compose 即可。

第二步：下载并准备 Docker 配置文件

Windows（CMD）

mkdir zotero-pdf2zh_docker
cd zotero-pdf2zh_docker

REM 下载
curl -L -o docker.zip https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/docker.zip

REM 解压（任选一种；如命令行解压失败，可在资源管理器中右键解压到当前目录）
powershell -Command "Expand-Archive -Path '.\docker.zip' -DestinationPath '.' -Force"
REM 或者（如果 tar 可用）
REM tar -xf docker.zip

REM 进入 docker 子目录（里面有 Dockerfile 和 docker-compose.yaml）
cd docker

macOS / Linux（终端）

mkdir -p zotero-pdf2zh_docker
cd zotero-pdf2zh_docker

# 下载
curl -L -o docker.zip https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/main/docker.zip

# 解压（任选其一）
unzip -o docker.zip -d .
# 或
# tar -xf docker.zip

# 进入 docker 子目录（里面有官方 Dockerfile 和 docker-compose.yaml）
cd docker

解压后的 docker/ 目录包含：

Dockerfile
docker-compose.yaml
config/         （空文件夹，用于挂载配置）
translated/     （空文件夹，用于挂载输出）

第三步：预拉取核心镜像 (推荐)

为避免首次启动时因网络问题导致超时，建议先手动拉取 pdf2zh_next 的 Docker 镜像。

docker pull awwaawwa/pdfmathtranslate-next:latest

第四步：启动服务

在 zotero-pdf2zh_docker/docker 目录下，执行以下命令：

docker compose up -d --build

当您看到类似下面的日志输出时，代表服务已成功启动：

* Running on http://127.0.0.1:8890
* Running on http://172.18.0.2:8890

常用 Docker 管理命令：

docker start zotero-pdf2zh      # 启动已存在的容器
docker stop zotero-pdf2zh       # 停止容器
docker logs -f zotero-pdf2zh    # 查看实时日志，用于排查问题
docker compose down             # 停止并移除容器

（可选）切换为 `pdf2zh` （1.x）

默认镜像是 pdf2zh_next。如果你只想用 1.x pdf2zh（byaidu/pdf2zh:1.9.6），按下述最小改动即可。

0）预拉取经典镜像

docker pull byaidu/pdf2zh:1.9.6

1) 修改 Dockerfile

A. 更换镜像变量，改为1.x

找到：

    ZOTERO_PDF2ZH_FROM_IMAGE=awwaawwa/pdfmathtranslate-next:latest

改为：

    ZOTERO_PDF2ZH_FROM_IMAGE=byaidu/pdf2zh:1.9.6

B. 删除“next 包装器”整段

找到

RUN printf '%s\n' \
  '#!/usr/bin/env bash' \
  'set -euo pipefail' \
  'img="${ZOTERO_PDF2ZH_FROM_IMAGE:-awwaawwa/pdfmathtranslate-next:latest}"' \
  'cid="$(cat /etc/hostname)"' \
  'exec docker run --rm --volumes-from "${cid}" -e TZ -e http_proxy -e https_proxy -e HF_ENDPOINT "$img" pdf2zh_next "$@"' \
  > /usr/local/bin/pdf2zh_next && chmod +x /usr/local/bin/pdf2zh_next

整块修改为：

RUN printf '%s\n' \
  '#!/usr/bin/env bash' \
  'set -euo pipefail' \
  'img="${ZOTERO_PDF2ZH_FROM_IMAGE:-byaidu/pdf2zh:1.9.6}"' \
  'cid="$(cat /etc/hostname)"' \
  'exec docker run --rm --volumes-from "${cid}" -e TZ -e http_proxy -e https_proxy -e HF_ENDPOINT "$img" pdf2zh "$@"' \
  > /usr/local/bin/pdf2zh && chmod +x /usr/local/bin/pdf2zh

其它内容（server.zip 下载、requirements 安装、entrypoint）保持不变。

2) 修改 `docker-compose.yaml`

找到

      ZOTERO_PDF2ZH_FROM_IMAGE: awwaawwa/pdfmathtranslate-next:latest

改为：

      ZOTERO_PDF2ZH_FROM_IMAGE: byaidu/pdf2zh:1.9.6

如需挂字体（可选，字体文件与 docker-compose.yaml 同级）：

volumes:
  - ./translated:/app/server/translated
  - ./config:/app/server/config
  - ./LXGWWenKai-Regular.ttf:/app/LXGWWenKai-Regular.ttf:ro   # 可选
  - /var/run/docker.sock:/var/run/docker.sock

3) 重构启动（在 `docker` 目录）

docker compose down
docker compose up -d --build

常用命令：

docker start zotero-pdf2zh      # 启动已存在的容器
docker stop zotero-pdf2zh       # 停止容器
docker logs -f zotero-pdf2zh    # 查看实时日志，用于排查问题
docker compose down             # 停止并移除容器

插件里把 翻译引擎 选成 pdf2zh。祝您使用愉快！

Part 3：连接 Zotero 并开始翻译

无论您选择哪种部署方式，最后一步都是在 Zotero 插件中配置并使用它。

插件设置：在 Zotero 中，导航至 “编辑” -> “首选项” -> “PDF2zh” 选项卡。
服务地址：确保服务地址与您的后端服务一致。默认是 http://127.0.0.1:8890 或 http://localhost:8890。如果您在启动时修改了端口，请在此处同步更新。
模型配置：在此处配置您的翻译引擎（如 pdf2zh_next）、API 服务商的 Base URL 和 API Key。
开始翻译：回到 Zotero 主界面，选中一篇或多篇文献条目，右键单击，在菜单中选择 “开始翻译”。

Part 4：常见问题解答（FAQ）

Q1：第一次翻译进度条卡在 translate 10/100 很久？
A：

建议开启代理/镜像加速首次资源下载；
或直接在 PDFMathTranslate-next Releases 下载 带 assets 的 Windows 压缩包（内置常用字体/资源），解压后双击 pdf2zh.exe，访问 WebUI http://127.0.0.1:7860/ 翻译任意 1 页触发资源释放。

Q2：Windows 报 “DLL 初始化失败/缺少运行库”？
A：安装 Microsoft Visual C++ 2015–2022（x64） 。

Q3：Zotero 无进度条、任务未启动？
A：优先检查 Zotero ↔ 本地服务 连通性（端口/回环地址/代理），并核对插件中的服务地址 http://localhost:8890 是否与后端一致（默认即为 8890）。

Q4：服务端返回 401/403/404/429 或端点不可达？
A：逐项核实 Base URL / API Key / 模型名 / 速率；根据服务商限制临时降低 QPS/并发，观察是否恢复。

Q5：线程/速率如何估算？
A：以服务商 RPM/TPM 为上限，从保守的 QPS 值启动并逐步压测： QPS = ⌊ RPM / 60 ⌋。

Q6：我实在是搞不定部署应该怎么办
A：打开网页：沉浸式翻译 BabelDOC 登陆账号拖入文件开始翻译

获取更多帮助

如果以上内容未能解决您的问题，可以通过以下渠道寻求支持：

阅读更详尽的常见问题文档
在项目的 GitHub Issues 区提交您的问题。
加入用户 QQ 群: 971960014 (入群验证: github)。提问时，请附上：
1）终端的完整报错日志（复制为文本.txt） 2）Zotero 插件的配置截图 3）报错弹窗截图 4）问题 PDF 文件。

感谢您的支持，祝您使用愉快！！