前言
安装Python和Zotero；安装uv或者conda二选一，我安装的是conda
建议下载3.12.0版本Python
插件目前支持Zotero 7以及Zotero 8
第一步：安装uv/conda
1.安装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"
# 方法二: pip安装
pip install uv
2.检查uv安装是否成功
# 显示uv版本号, 则uv安装完成（必做）
# 如果您的uv安装检查失败了，请您优先排查这个问题，不要进行第二步操作。
uv --version
3.如果检查失败 需要将uv执行路径添加到全局路径，并重启终端。注意将Username替换为您自己的用户名。
# MacOS/Linux
export PATH="$PATH:/Users/Username/.local/bin"
# Windows
$env:Path = "C:\Users\Username\.local\bin;$env:Path"
conda安装
安装conda 参考本链接安装: https://www.anaconda.com/docs/getting-started/miniconda/install#windows-command-prompt
检查conda安装是否成功
# 显示conda版本号, 则conda安装完成
# 如果您的conda安装检查失败了，请您优先排查这个问题，不要进行第二步操作。
conda --version
第二步：下载项目文件
创建文件夹（命名为：zotero-pdf2zh）
进入文件夹，右键点击“在终端中打开”并执行三条指令
下载：wget https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/refs/heads/main/server.zip -OutFile server.zip
解压缩：Expand-Archive server.zip -DestinationPath .
进入server文件夹：cd server
准备环境并执行
安装依赖：pip install -r requirements.txt
如果选择conda
预热版本：
# 1. 利用conda预热(首次安装)
# Windows用户:
.\install-with-conda.bat --warmup
# MacOS/Linux用户:
./install-with-conda.sh --warmup
# 预热后，您需要检查命令行中是否提示安装成功，如果安装失败，请不要进行下一步
# 2. 执行脚本
python server.py --env_tool=conda --skip_install=True
# install-with-conda.sh有三个选项:
# --warmup 对babeldoc的资源文件进行预热(需要一些时间)
# --upgrade 对当前包进行升级
# --no-mirror 不使用国内镜像源
非预热版本：
# 指定虚拟环境工具为conda
python server.py --env_tool=conda
如果选择uv
预热版本：
# 1. 利用uv预热(首次安装)
# Windows用户:
.\install-with-uv.bat --warmup
# MacOS/Linux用户:
./install-with-uv.sh --warmup
# 预热后，您需要检查命令行中是否提示安装成功，如果安装失败，请不要进行下一步
# 2. 执行脚本
python server.py --skip_install=True
# install-with-uv.sh有三个选项:
# --warmup 对babeldoc的资源文件进行预热(需要一些时间)
# --upgrade 对当前包进行升级
# --no-mirror 不使用国内镜像源
非预热版本：
python server.py
第四步：下载并安装插件
下载链接：https://github.com/guaguastandup/zotero-pdf2zh/releases/download/v3.0.35/zotero-pdf-2-zh.xpihttps://github.com/guaguastandup/zotero-pdf2zh/releases/download/v3.0.35/zotero-pdf-2-zh.xpi
您可以在zotero中检查更新，或选择自动更新，来获取最新版本插件。
在zotero中打开“工具-插件”，将xpi文件拖入，进行安装。（若拖入后功能未生效，请重启Zotero后再试）
第五步：Zotero端插件设置
配置选项说明
切换翻译引擎
pdf2zh/pdf2zh_next，界面将显示不同引擎的翻译配置关于qps和poolsize选项：请参考您的服务商（例如zhipu）。
- 计算公式:
qps = rpm / 60 - 对于上游为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文件中的字段相对应), 本功能将在未来继续优化, 可参考文档
翻译服务说明
单击LLM API配置管理处的新增，弹出此窗口，进行服务配置。
- 您可以为同一个服务添加多种配置，但是您只能激活其中一种，在翻译时会使用您激活的配置
- 在配置LLM API后，您还需要在上方设置的翻译服务处选择您需要使用的服务
💡 翻译服务介绍
| 服务类型 | 服务名称 | 服务介绍 | 💡注意事项 |
|---|---|---|---|
| 免费&免配置的翻译服务 | siliconflowfree | 基于硅基流动提供的GLM4-9B模型, 仅支持翻译引擎pdf2zh_next，由@硅基流动、@pdf2zh_next 和 @BabelDOC联合提供服务 | 1. 此服务无需选择qps，默认为40 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 v3服务即可 |
除了免费服务，您均需要配置自己的API Key和URL才可以使用翻译服务（某些服务不需要配置URL，可以忽略）
您可以根据实际情况自行调整并发数
openailiked服务选项可以填写所有兼容openai格式的LLM服务, 您需要填写您的LLM服务供应商提供的URL, API Key, Model名称等信息。
- 示例: 火山引擎url填写为
https://ark.cn-beijing.volces.com/api/v3
- 示例: 火山引擎url填写为
第六步： 关于翻译选项
在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竖向裁剪为单栏文件，再左右拼接。 |
第七步: 关于包更新(New)
zotero插件和server脚本均具有自动更新功能, 但是为了使用最新版本babeldoc和pdf2zh_next, 您需要进行下列操作:
进入server文件夹
进入虚拟环境: 名称为
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
- 更新
# conda pip install --upgrade pdf2zh_next babeldoc # uv uv pip install --upgrade pdf2zh_next babeldoc
