Zotero PDF2zh
[](https://www.zotero.org)
[](https://www.zotero.org/support/beta_builds)
[](https://github.com/windingwind/zotero-plugin-template)
[](https://github.com/guaguastandup/zotero-pdf2zh/blob/main/LICENSE)
[](https://zread.ai/guaguastandup/zotero-pdf2zh)
在Zotero中使用[PDF2zh](https://github.com/Byaidu/PDFMathTranslate)和[PDF2zh_next](https://github.com/PDFMathTranslate/PDFMathTranslate-next)
**当前版本信息：** server.zip v4.0.4 | 插件 xpi v4.0.1
**📚 项目文档：** [zotero-pdf2zh.github.io](https://zotero-pdf2zh.github.io)
**📝 其他语言 / Other Languages:**
[English](./i18n/README.en.md) | [日本語](./i18n/README.ja.md) | [한국어](./i18n/README.ko.md) | [Italiano](./i18n/README.it.md) | [Français](./i18n/README.fr.md)
> **Note:** The translations above were generated by AI and may contain inaccuracies. For the most accurate information, please refer to this document.
> 📢: 桌面端构建中(Coming Soon!)，改动较大，有新的功能&修复了旧bug，暂不接收新的Pull Request
## 📖 目录
- [如何使用本插件](#如何使用本插件)
- [安装说明](#安装说明)
- [第零步：安装Python和Zotero](#第零步安装python和zotero)
- [第一步：安装uv/conda](#第一步安装uvconda)
- [第二步：下载项目文件](#第二步下载项目文件)
- [第三步：启动服务](#第三步启动服务)
- [第四步：下载并安装插件](#第四步下载并安装插件)
- [第五步：Zotero端插件设置](#第五步zotero端插件设置)
- [第六步：关于翻译选项](#第六步-关于翻译选项)
- [第七步：关于包更新](#第七步-关于包更新)
- [其他安装方法](#其他安装方法)
- [常见问题（FAQ）](#常见问题faq)
- [关于网络](#关于网络)
- [关于环境](#关于环境)
- [关于翻译服务](#关于翻译服务)
- [关于OCR/扫描件](#关于ocr扫描件)
- [关于翻译效果](#关于翻译效果)
- [关于插件功能](#关于插件功能)
- [关于提问](#关于提问)
- [关于支持本插件](#关于支持本插件)
- [致谢](#致谢)
- [贡献者](#贡献者)
- [如何支持我](#如何支持我)
- [开源协议与使用声明](#开源协议与使用声明)
---
# 如何使用本插件
本指南将引导您完成 Zotero PDF2zh 插件的安装和配置。
❓ 遇到问题
- 跳转至本项目总结的常见问题：[常见问题(FAQ)](https://github.com/guaguastandup/zotero-pdf2zh?tab=readme-ov-file#%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98faq)
- 基础问题（例如如何安装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**：[下载链接](https://www.python.org/downloads/)，建议安装 3.12 版本
- **Zotero**：支持 [Zotero 7](https://www.zotero.org) 和 [Zotero 8](https://www.zotero.org/download/)（适配 by @[Aphcity](https://github.com/Aphcity)）
- **打开命令行工具**（后续步骤都在命令行中执行）：
- **Windows**：按 `Win + R` → 输入 `cmd` → 回车（建议以**管理员身份运行**）
- **macOS**：按 `Cmd + 空格` → 输入"终端" → 回车
- **Linux**：`Ctrl + Alt + T`
## 第一步：安装uv/conda
选择一个环境管理工具。如果不确定选哪个，推荐 uv。
**uv安装(推荐)**
```shell
# 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 路径添加到环境变量并重启终端：
```shell
# MacOS/Linux
export PATH="$HOME/.local/bin:$PATH"
# Windows PowerShell
$env:Path = "$env:USERPROFILE\.local\bin;$env:Path"
```
**conda安装**
参考 [Miniconda 安装指南](https://www.anaconda.com/docs/getting-started/miniconda/install#windows-command-prompt)进行安装，安装后执行 `conda --version` 验证。
## 第二步：下载项目文件
> ⚠️ **Windows用户注意**：请勿在C盘（系统盘）下创建项目文件夹，建议在D盘或其他非系统盘操作。例如：先执行 `D:` 切换到D盘，再执行后续命令。
```shell
# 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 用户（推荐）**
```shell
uv run --python 3.12 --with-requirements requirements.txt server.py
```
**conda 用户**
```shell
# 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[下载链接](https://github.com/guaguastandup/zotero-pdf2zh/releases/download/v4.0.1/zotero-pdf-2-zh.xpi)
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](https://www.bigmodel.cn/dev/howuse/rate-limits)）
>
>- 计算公式: `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`文件中的字段相对应), 本功能将在未来继续优化, 可参考[文档](./server/doc/extraData.md)
**网页端查看翻译进度**
服务启动后，可在浏览器中访问 `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](https://github.com/Byaidu/PDFMathTranslate) | [PDFMathTranslate-next](https://github.com/PDFMathTranslate/PDFMathTranslate-next) |
**翻译服务配置**
配置翻译服务需完成两步：
**第一步：添加API配置**
在"LLM API配置管理"区域点击"新增"，填写服务配置信息。同一服务可添加多个配置，但只能激活其中一个。
**第二步：选择翻译服务**
在页面顶部的"翻译服务"下拉菜单中，选择要使用的服务名称。
>警告：仅添加API配置不会生效，必须完成第二步选择服务，翻译功能才能使用。
**💡 翻译服务介绍(必读)**
| 服务类型 | 服务名称 | 服务介绍 | 💡注意事项 |
| ----------------------- | ---------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| 免费&免配置的翻译服务 | siliconflowfree | 基于硅基流动提供的GLM4-9B模型, 仅支持翻译引擎pdf2zh_next，由[@硅基流动](https://www.siliconflow.cn/)、[@pdf2zh_next](https://github.com/PDFMathTranslate/PDFMathTranslate-next) 和 [@BabelDOC](https://github.com/funstory-ai/BabelDOC)联合提供服务 | 1. 此服务无需选择qps，默认为20
2.此服务可能会存在漏翻译的情况，如果需要高质量翻译请优先选择其他服务
3. 此服务仅支持pdf2zh_next引擎 |
| 免费&免配置的翻译服务 | bing/google | bing/google的官方机器翻译 | bing和goole的翻译服务都存在限流，如果翻译失败，请将并发数设置调至2及以下重试 |
| 具有优惠/赠送的翻译服务 | openaliked | 加入[火山引擎协作计划](https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement?OpenAuthorizeModal=true&OpenTokenDrawer=false)，个人用户每个模型每天最多赠送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`
## 第六步： 关于翻译选项
在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**竖向裁剪为单栏文件**，再左右拼接。 | 
|
**您可以多选条目，右键菜单，然后进行批量PDF翻译**
## 第七步: 关于包更新
zotero插件和server脚本均具有自动更新功能, 但是为了使用最新版本babeldoc和pdf2zh_next, 您需要进行下列操作:
0. 进入server文件夹
1. 进入虚拟环境: 名称为`zotero-pdf2zh-next-venv`
```shell
# conda
conda activate zotero-pdf2zh-next-venv
# uv
## MacOS/Linux
source ./zotero-pdf2zh-venv-next/bin/activate
## Windows
.\zotero-pdf2zh-next-venv\Scripts\activate
```
2. 更新
```shell
# 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](https://github.com/PDFMathTranslate-next/PDFMathTranslate-next/releases) 页面，下载 `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`
3. 运行服务：
```shell
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](https://aka.ms/vs/17/release/vc_redist.x64.exe)
- exe模式目前可能存在一些兼容性问题，如果遇到问题建议使用虚拟环境方式
### Docker 部署
- zotero-pdf2zh [docker链接](https://hub.docker.com/r/vanxv/zotero-pdf2zh) by [@xucongyong](https://github.com/xucongyong)
- 请参考：[Docker部署方法一](./docker/README.md) by [@Rosetears520](https://github.com/Rosetears520)
- 请参考：[Docker部署方法二](./docker2/README.md) by [@taozhe6](https://github.com/taozhe6)
### Homebrew/Linuxbrew 部署（MacOS/Linux用户）
- 参考：[做了一个 homebrew 的 tap，便于 mac 用户直接使用 #187](https://github.com/guaguastandup/zotero-pdf2zh/issues/187) by [@NightWatcher314](https://github.com/NightWatcher314)
- 仓库链接: [NightWatcher314/zotero-pdf2zh-server](https://github.com/NightWatcher314/zotero-pdf2zh-server)
### 不使用虚拟环境管理
如果您只想使用 pdf2zh_next/pdf2zh 引擎中的一个，并且全局 Python 版本为 3.12.0，可以不使用虚拟环境管理。
> ⚠️ **注意**：不使用虚拟环境管理时，您需要确保：
> - 全局 Python 版本为 3.12 或更高
> - 已手动安装所需的依赖包
#### uv 用户（推荐）
```shell
# 创建固定主虚拟环境（只需执行一次）
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 用户
```shell
# 创建主虚拟环境（只需执行一次）
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
```
#### 手动安装依赖（如果只需要特定引擎）
```shell
# 如果只使用 pdf2zh:
pip install pdf2zh==1.9.11 numpy==2.2.0
# 如果只使用 pdf2zh_next:
pip install pdf2zh_next
```
### 一键启动脚本
每次翻译都需要打开终端执行启动命令，为了方便日常使用，您可以配置一键启动：
**方式一：使用 uv 的用户**
**Windows 用户 - 创建桌面快捷脚本：**
1. 先在当前终端输入 `cd` 命令查看完整路径
```shell
cd
```
终端会显示类似：`D:\zotero-pdf2zh\server` 的路径
2. 在桌面新建一个文本文件，右键编辑，写入以下内容：
```bat
@echo off
cd /d <粘贴刚才复制的路径>
uv run --python 3.12 --with-requirements requirements.txt server.py
pause
```
3. 将 `<粘贴刚才复制的路径>` 替换为您复制的实际路径
4. 重命名为 `start-pdf2zh.bat`（后缀名必须是 `.bat`）
5. 保存后双击即可启动
**macOS / Linux 用户 - 配置别名（alias）：**
1. 打开终端，编辑 shell 配置文件：
```shell
# 如果使用 zsh（macOS 默认）
nano ~/.zshrc
# 如果使用 bash
nano ~/.bashrc
```
2. 在文件末尾添加别名（请根据实际路径修改）：
```shell
alias pdf2zh-start='cd /path/to/zotero-pdf2zh/server && uv run --python 3.12 --with-requirements requirements.txt server.py'
```
3. 保存后执行：
```shell
source ~/.zshrc
# 或
source ~/.bashrc
```
4. 之后只需在终端输入 `pdf2zh-start` 即可一键启动
**方式二：使用 conda 的用户**
**Windows 用户 - 创建桌面快捷脚本：**
1. 先在当前终端输入 `cd` 命令查看完整路径
```shell
cd
```
终端会显示类似：`D:\zotero-pdf2zh\server` 的路径
2. 在桌面新建一个文本文件，右键编辑，写入以下内容：
```bat
@echo off
cd /d <粘贴刚才复制的路径>
python server.py --env_tool=conda
pause
```
3. 将 `<粘贴刚才复制的路径>` 替换为您复制的实际路径
4. 重命名为 `start-pdf2zh-conda.bat`（后缀名必须是 `.bat`）
5. 保存后双击即可启动
**macOS / Linux 用户 - 配置别名（alias）：**
1. 打开终端，编辑 shell 配置文件：
```shell
# 如果使用 zsh（macOS 默认）
nano ~/.zshrc
# 如果使用 bash
nano ~/.bashrc
```
2. 在文件末尾添加别名（请根据实际路径修改）：
```shell
alias pdf2zh-start='cd /path/to/zotero-pdf2zh/server && python server.py --env_tool=conda'
```
> 💡 注意：使用此别名前，请确保已初始化 conda（通常在安装 conda 后会自动添加到 `.bashrc` 或 `.zshrc` 中）
3. 保存后执行：
```shell
source ~/.zshrc
# 或
source ~/.bashrc
```
4. 之后只需在终端输入 `pdf2zh-start` 即可一键启动
# 常见问题（FAQ）
### 关于网络
- **[🔥高频问题]Q：我遇到了网络问题（NetworkError when attempting to fetch resource），该怎么办？**
- A：
- **首先点击插件设置页面中"Python Server IP"旁边的"检查连接"按钮**，查看连接状态
- 若显示连接失败，请按以下步骤排查：
- 确保插件是最新版：版本号4.0.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](https://aka.ms/vs/17/release/vc_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，可以尝试安装以下三个文件：
- [VC_redist.x86.exe](https://aka.ms/vs/17/release/vc_redist.x86.exe)（32位版本）
- [VC_redist.x15.x64.exe](https://aka.ms/vs/16/release/vc_redist.x64.exe)（64位版本，2015-2019）
- [VC_redist.x17.x64.exe](https://aka.ms/vs/17/release/vc_redist.x64.exe)（64位版本，2015-2022）
- 如果您在QQ群中，也可以直接在群文件中下载这三个文件
- 也许您正在使用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插件配置中，把提取术语表选项关闭，这个选项会消耗较多Token
- **[🔥高频问题]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服务是否正常。
### 关于插件功能
- **Q：我不知道zotero插件里的各个功能是什么意思**
- A：您可以自由尝试，请尽量不要对这些问题进行提问，翻译引擎具有缓存的设置，也就是说您重复对同一篇文献进行翻译时，可能不会消耗过多的Token（不能保证完全不消耗）
### 关于提问
**提问前请先尝试以下方法：**
- 将终端报错信息发送给AI（ChatGPT、Gemini、DeepSeek等）进行分析
- 在本文档中搜索错误关键词或查阅相关章节
**如需在群内提问，请提供：**
- 终端完整输出（复制到txt文件）
- Zotero设置截图
- Zotero弹窗截图
- 说明您已尝试过的解决方法
- **Q：我在群里问问题，怎么没人回复我？**
- A：
- 请确认您的问题不属于常见问题，或在问题描述中说明"已查阅常见问题但仍未解决"
- 请提供终端输出、Zotero设置截图和弹窗截图，以便定位问题
- 如果被漏看，可以稍后重新发或@群主
- **Q：可是我给作者打赏了，希望能得到优先支持。**
- A：非常感谢您的支持！打赏是对项目的肯定和鼓励，如果打赏后遇到问题，欢迎私聊群主，我会尽力协助您解决。
### 关于支持本插件
- **Q：我很喜欢这个插件，想要提供支持，让这个插件更好地长期运行，我该怎么做？**
- A：
- 您可以继续下滑，找到支持本项目开发者的方式（支付码/爱发电等方式，您的昵称将出现在赞助者名单）
- 您可以参与本项目的开发
- 您可以为本项目点一个star
- 您可以在issue区提出您期望的未来功能（需是合理的功能建议）
- 您可以将本插件推荐给身边的朋友，并且在他们的安装过程中给出一些指导
# 致谢
- [PDF2zh](https://github.com/Byaidu/PDFMathTranslate) by [@Byaidu](https://github.com/Byaidu)
- [PDF2zh_next](https://github.com/PDFMathTranslate-next/PDFMathTranslate-next) by [@awwaawwa](https://github.com/awwaawwa)
- [zotero-plugin-template](https://github.com/windingwind/zotero-plugin-template) by [@windingwind](https://github.com/windingwind)
- [沉浸式翻译](https://immersivetranslate.com)为本项目的活跃贡献者赞助每月Pro会员兑换码，详情请见：[CONTRIBUTOR_REWARD.md](https://github.com/funstory-ai/BabelDOC/blob/main/docs/CONTRIBUTOR_REWARD.md)
# 贡献者
> 📢: 桌面端构建中(Coming Soon!)，改动较大，有新的功能&修复了旧bug，暂不接收新的Pull Request
感谢各位贡献者对项目的付出!!
**贡献者名单**：
[](https://github.com/guaguastandup)
[](https://github.com/Aphcity)
[](https://github.com/Bocheng-L)
[](https://github.com/htyxyt)
[](https://github.com/Rosetears520)
[](https://github.com/taozhe6)
[](https://github.com/Norhua)
[](https://github.com/KANIKIG)
[](https://github.com/Snowflake-Pink)
[](https://github.com/LinHuanli)
[](https://github.com/chunzhimoe)
[](https://github.com/tcpsoftware)
# 如何支持我
💐 免费开源插件，您的支持是我继续开发的动力～祝您科研/工作/学习顺利!
- 赞助时, 请在备注中留下您希望出现在赞助者名单的姓名或昵称💗
- ☕️ [Wechat微信/Alipay支付宝](https://github.com/guaguastandup/guaguastandup)
- 🐳 [爱发电](https://afdian.com/a/guaguastandup)
- 🤖 【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
- 如果您希望在赞助者名单中补充您的昵称和您的个人主页链接，也请联系我~
赞助者名单
感谢您的支持! 您的支持是我开发的动力~
# Star History
[](https://www.star-history.com/#guaguastandup/zotero-pdf2zh&Date)
# 开源协议与使用声明
本项目采用开源协议发布，所有开发者在使用本插件代码时必须遵循以下原则：
1. **遵守开源协议**：使用本项目的代码必须遵循本项目所采用的AGPL开源协议（详见 [LICENSE](./LICENSE) 文件），包括但不限于保留版权声明、开源修改后的代码等。
2. **禁止商业倒卖**：本插件为**免费开源项目**，严禁任何形式的商业倒卖行为，包括但不限于：
- 将本插件打包后以收费形式出售
- 以"代安装"、"技术服务"等名义收取高额费用后交付本插件
- 将本插件作为付费产品的一部分进行销售
> ⚠️ **特别提醒**：商业贩子请勿加入QQ群提问，不要消耗维护者的精力。一旦发现，将直接移出群聊并拉黑。
3. **合理使用**：欢迎个人学习、研究、非商业用途的使用。如需商业使用，请联系作者获取授权。
4. **尊重开源精神**：我们鼓励开发者基于本项目进行改进和贡献，但请尊重原作者的劳动成果，遵守开源社区的基本准则。
如发现违反上述原则的行为，作者保留追究法律责任的权利。
