第一章：技术概述
什么是 PDFMathTranslate
PDFMathTranslate（命令行工具名 pdf2zh）是一个开源的 PDF 科学文档翻译工具，其核心能力是在翻译 PDF 全文的同时，完整保留原始排版、数学公式、图表、目录和批注。它是世界上第一个以开源形式实现的"保排版 PDF 翻译"软件，论文已被 EMNLP 2025（计算语言学顶级会议）录用。
一句话定义：把一篇外文 PDF 论文丢进去，出来一篇排版几乎一模一样的中文 PDF，公式、图表、参考文献全部原样保留。
关键数据
| 指标 | 数值 |
|---|---|
| GitHub Stars | 33k+ |
| PyPI 下载量 | 222k+ |
| Fork 数 | 3k+ |
| 贡献者 | 57 人 |
| 许可证 | AGPL-3.0 |
| 编程语言 | Python 97.9% |
| 学术发表 | EMNLP 2025 Demo |
| 最新版本 | v1.9.11（稳定版）/ v2.0（实验版） |
技术定位
PDFMathTranslate 属于 文档智能（Document AI）+ 机器翻译（MT） 的交叉领域。它不发明翻译算法，也不发明 PDF 解析算法，而是做了一件事：把两者精确地"对齐"和"缝合"。
技术体系中的位置：
🖼 飞书画板（暂不支持内嵌预览，请在原文查看）
核心价值
- 公式不丢不乱 — 数学公式在翻译过程中被精确保护，不会被翻译引擎误读
- 排版高度还原 — 页面布局、字体、字号、分栏、页眉页脚尽量保持原样
- 翻译引擎可插拔 — 支持 Google / DeepL / OpenAI / Ollama / Azure / Claude 等十余种翻译后端
- 多形态部署 — CLI / GUI（Gradio）/ Docker / MCP Server / Zotero 插件 / HTTP API
- 完全开源免费 — AGPL-3.0，可自建服务
第二章：问题背景与痛点
学术翻译的传统困境
在 PDFMathTranslate 出现之前，翻译一篇英文学术论文通常有以下几种方式：
方式一：复制粘贴到翻译工具
- 打开 PDF，手动选中文本
- 粘贴到 Google Translate / DeepL / ChatGPT
- 翻译结果复制到 Word
- 手动重新排版 痛点：公式会变成乱码，图表丢失，参考文献格式混乱，一份 20 页的论文可能需要 2-3 小时。
方式二：上传到在线翻译平台
Google Translate 文档翻译、DeepL Pro 等可以上传 PDF 直接翻译。
痛点：公式被破坏或丢失，多栏排版被压成单栏，表格错位，页码和目录完全失效。
方式三：使用 OCR 工具先转文字再翻译
先用 OCR 把 PDF 转成纯文本，再用翻译工具处理。
痛点：OCR 对数学公式的识别准确率很低，公式被"文本化"后不可逆地丢失了 LaTeX 结构信息。
五大结构性痛点
| 痛点 | 说明 | 严重程度 |
|---|---|---|
| 公式破坏 | 翻译引擎把 LaTeX 公式当普通文本处理，导致公式消失或变成乱码 | 致命 |
| 排版丢失 | 多栏布局、页眉页脚、脚注、目录在翻译后全部消失 | 严重 |
| 图表错位 | 图注被翻译但图本身被移位，表格结构被破坏 | 严重 |
| 批量低效 | 每篇论文都需要手动处理，无法自动化批量翻译 | 中等 |
| 隐私风险 | 在线翻译平台需要上传论文到第三方服务器 | 中等 |
为什么这个问题很难
PDF 的本质是一个排版指令集，而不是结构化文档。一个数学公式在 PDF 中不是一段 LaTeX 代码，而是一组绘制指令（"在坐标 (120, 340) 处画一个积分号"）。这意味着：
- 解析难：需要从绘制指令中"逆向"还原出文本内容
- 分离难：需要精确区分哪些是文本、哪些是公式、哪些是图表
- 重组难：翻译后的文本长度变化，需要重新计算排版位置
- 字体难：目标语言可能需要完全不同的字体集 PDFMathTranslate 本质上就是在优化这条链路：PDF 解析 → 元素分类 → 文本翻译 → 原位替换 → 排版修正 → 输出新 PDF。
第三章：核心思想
一句话概括
PDFMathTranslate 的核心思想是：不破坏 PDF 的内部结构，只替换其中的文本内容，让公式、图表、排版全部"原地不动"。
通俗类比
想象你有一本英文书，每一页的公式和图片都用透明胶带牢牢贴好了。PDFMathTranslate 就像一个"精准替换工"——它只把英文文字部分用中文替换掉，公式和图片的透明胶带完全不碰，替换完后页面的样子和原来几乎一模一样。
六大设计原则
1. 原位替换（In-place Replacement）
不重新排版，不重新生成 PDF，而是在原始 PDF 的内部结构中精确替换文本字符串。这就像在 PDF 的"源代码"里做 find-and-replace。
2. 公式隔离（Formula Isolation）
通过布局检测模型识别出公式区域，翻译时完全跳过这些区域，确保公式不会被翻译引擎误读。
3. 翻译引擎解耦（Engine Decoupling）
翻译能力完全外包给第三方 API（Google / DeepL / OpenAI 等），工具本身只负责"解析 → 分发 → 回填"的管线。
4. 字体自适应（Font Adaptation）
翻译后的目标语言（如中文）需要不同的字体。工具内置了多语言字体支持（Go Noto Universal），并支持字体子集嵌入。
5. 双模式输出（Dual Output）
同时生成纯译文版（-mono.pdf）和双语对照版（-dual.pdf），满足不同阅读需求。
6. 渐进式处理（Progressive Processing）
支持部分翻译（-p 参数指定页码范围）、缓存复用（已翻译内容不重复调用 API）、批量目录处理（--dir 参数）。
与传统方案的本质区别
| 维度 | 传统方案 | PDFMathTranslate |
|---|---|---|
| 处理粒度 | 整页/整文档级 | 文本块级别 |
| 公式处理 | OCR 后文本化 | 检测后跳过 |
| 排版策略 | 重新生成 | 原位替换 |
| 翻译引擎 | 固定 | 可插拔 |
| 部署方式 | 云端 SaaS | 本地/自托管 |
第四章：核心原理
四层处理管线
PDFMathTranslate 的翻译过程分为四个核心阶段：
🖼 飞书画板（暂不支持内嵌预览，请在原文查看）
第一阶段：PDF 解析与文本提取
核心依赖：PdfMiner.six + PyMuPDF
- PDF 结构解析：PdfMiner 解析 PDF 的内部对象树（页面 → 内容流 → 文本对象），提取每个文本块的坐标、字体、字号信息
- 页面元素提取：PyMuPDF 提取页面上的文字、图片、路径等所有可绘制元素
- 文本流重组：将分散的文本操作符重新组装成有意义的文本行和段落 关键技术细节：
- PDF 的文本以操作符形式存储（
Tj、TJ等），每个操作符对应一段文本 - 文本坐标是绝对定位的（页面坐标系），需要转换为相对位置才能理解布局
- 字体信息包含在 PDF 的 Font 字典中，需要解析编码映射
第二阶段：智能元素分类
核心依赖：DocLayout-YOLO（ONNX 推理）
这是 PDFMathTranslate 的关键创新点。它使用一个基于 YOLO 的文档布局检测模型，对 PDF 的每一页进行元素级分类：
| 检测类别 | 处理方式 |
|---|---|
| 正文文本（Text） | 送入翻译引擎 |
| 标题（Title） | 送入翻译引擎 |
| 数学公式（Equation） | 跳过，保持原样 |
| 图（Figure） | 跳过，保持原样 |
| 表格（Table） | 提取文本后翻译，保留表格结构 |
| 页眉页脚（Header/Footer） | 跳过或翻译 |
| 脚注（Footnote） | 送入翻译引擎 |
| 目录（TOC） | 特殊处理，保留链接 |
检测模型：wybxc/DocLayout-YOLO-DocStructBench-onnx（约 100MB），首次使用自动下载，Docker 镜像已内置。
第三阶段：文本翻译
核心机制：多线程批量翻译
- 文本分块：按段落和语义单元对文本进行分块，避免句子被截断
- 翻译调度：多线程并发调用翻译 API，每个线程独立处理一个文本块
- 缓存机制：已翻译的文本块会被缓存，重复文档或重试时跳过已翻译部分
- 自定义提示词：通过
--prompt参数可以注入领域术语和翻译风格指令 支持的翻译服务（截至 v1.9.11）：
| 服务 | 类型 | 备注 |
|---|---|---|
| 免费 | 默认服务 | |
| DeepL | 付费 API | 翻译质量较高 |
| OpenAI | 付费 API | GPT-4o / GPT-4o-mini |
| Claude | 付费 API | Anthropic Claude |
| Azure | 付费 API | 微软翻译服务 |
| Ollama | 本地 | 完全离线，支持 Llama/Qwen 等 |
| Bing | 免费 | 微软必应翻译 |
| MiniMax | 付费 API | 国内大模型 |
| OpenAI-Compatible | 通用 | 任意兼容 OpenAI API 格式的服务 |
| BabelDOC | 实验性 | 沉浸式翻译后端 |
第四阶段：原位回填与 PDF 生成
核心依赖：PyMuPDF
- 文本替换：在 PDF 的文本操作符中，将原始文本替换为翻译后的文本
- 字体处理：为目标语言的字符嵌入合适的字体（Go Noto Universal），可选跳过字体子集以加速（
--skip-subset-fonts） - 坐标调整：翻译后的文本长度可能变化，需要微调字符间距和位置以避免溢出
- 文档合并：将处理后的页面重新组装成完整的 PDF 文件 输出文件：
{filename}-mono.pdf— 纯译文版{filename}-dual.pdf— 双语对照版（原文和译文交替显示）
v2.0 实验性内核
2026 年 3 月，项目发布了 v2.0 实验版（--mode precise），使用新的翻译内核：
- 改进了跨栏、跨页的语义一致性
- 动态缩放处理（文本长度变化时的自适应）
- 更好的 PDF 兼容性（处理更多边缘情况）
- 独立仓库：PDFMathTranslate/PDFMathTranslate-next
第五章：系统架构
整体架构
🖼 飞书画板（暂不支持内嵌预览，请在原文查看）
目录结构
PDFMathTranslate/
├── pdf2zh/ # 核心包
│ ├── __init__.py
│ ├── main.py # CLI 入口
│ ├── converter.py # PDF 转换核心逻辑
│ ├── translator.py # 翻译引擎抽象层
│ ├── doclayout.py # DocLayout-YOLO 布局检测
│ ├── font.py # 字体处理
│ └── gui.py # Gradio GUI
├── docs/ # 文档
│ ├── ADVANCED.md # 高级用法
│ ├── APIS.md # API 文档
│ ├── README_zh-CN.md # 中文 README
│ └── images/ # 文档图片
├── script/ # 构建/部署脚本
├── test/ # 测试用例
├── Dockerfile # Docker 构建
├── docker-compose.yml # Docker Compose
├── pyproject.toml # 项目配置
└── LICENSE # AGPL-3.0
核心模块关系
| 模块 | 职责 | 关键依赖 |
|---|---|---|
main.py |
CLI 参数解析、流程编排 | argparse |
converter.py |
PDF 解析 → 分类 → 翻译 → 回填的完整管线 | PdfMiner, PyMuPDF |
translator.py |
翻译 API 调用、缓存管理、多线程调度 | requests, openai |
doclayout.py |
加载 ONNX 模型、页面布局检测 | onnxruntime |
font.py |
多语言字体加载、子集嵌入 | PyMuPDF |
gui.py |
Gradio Web UI | gradio |
数据流链路
PDF 文件
→ PdfMiner 解析出文本块（坐标 + 字体 + 内容）
→ DocLayout-YOLO 检测页面布局（公式/文本/图表区域）
→ 分类器标记每个文本块的处理策略
→ 翻译调度器分批发送待翻译文本
→ 翻译 API 返回译文
→ 缓存层存储译文（避免重复调用）
→ PyMuPDF 在原始 PDF 中替换文本
→ 字体引擎嵌入目标语言字体
→ 输出 mono.pdf + dual.pdf
第六章：关键流程
流程一：CLI 单文件翻译（完整时序）
🖼 飞书画板（暂不支持内嵌预览，请在原文查看）
流程二：GUI 翻译（Gradio Web UI）
- 用户打开
http://localhost:7860/ - 上传 PDF 文件或输入 URL
- 选择源语言、目标语言、翻译服务
- 可选：配置 API Key、自定义提示词
- 点击"翻译"，后台执行与 CLI 相同的管线
- 实时显示翻译进度
- 完成后提供预览和下载
流程三：Docker 部署翻译
docker pull byaidu/pdf2zh
docker run -d -p 7860:7860 byaidu/pdf2zh
Docker 镜像特点：
- ONNX 模型和字体已内置（约 100MB），无需额外下载
- 首次启动时自动预热模型（Dockerfile RUN 指令）
- 支持环境变量配置翻译服务密钥
流程四：MCP Server 模式
pdf2zh --mcp # STDIO 模式
pdf2zh --mcp --sse # SSE 模式
MCP 模式允许其他 AI Agent（如 Claude Desktop、Cursor）通过 Model Context Protocol 调用 PDFMathTranslate 的翻译能力。
流程五：批处理模式
pdf2zh --dir /path/to/papers/ -s openai -li en -lo zh
遍历目录下所有 PDF 文件，逐个翻译。结合 --config 参数可以统一配置翻译选项。
第七章：和相似技术的关系与区别
七维度对比矩阵
| 维度 | PDFMathTranslate | 沉浸式翻译 BabelDOC | Mathpix | DeepL Pro | Google Translate |
|---|---|---|---|---|---|
| 公式保留 | 优秀（YOLO检测跳过） | 良好 | 优秀 | 较差 | 差 |
| 排版保留 | 优秀（原位替换） | 良好 | 优秀 | 一般 | 差 |
| 翻译引擎 | 可插拔（10+种） | 内置+DeepL/OpenAI | DeepL | DeepL | |
| 价格 | 免费开源 | 免费+付费Pro | 付费 | 付费 | 免费（有限额） |
| 部署方式 | 本地/Docker/云 | 浏览器扩展 | 云端SaaS | 云端SaaS | 云端SaaS |
| OCR质量 | 良好 | 良好 | 业界最佳 | N/A | 一般 |
| 开源自托管 | 是 | 否 | 否 | 否 | 否 |
与各技术的详细对比
vs 沉浸式翻译（Immersive Translate / BabelDOC）
- 关系：互补 + 集成。PDFMathTranslate 的
--babeldoc参数可以直接调用 BabelDOC 后端 - 区别：沉浸式翻译是浏览器扩展，侧重网页即时翻译；PDFMathTranslate 是离线工具，侧重学术 PDF 的完整翻译
- 选择：日常网页阅读用沉浸式翻译；批量翻译学术论文用 PDFMathTranslate
vs Mathpix
- 关系：竞争。两者都定位为学术文档工具
- 区别：Mathpix 的 OCR 质量业界顶尖（尤其是手写公式），但价格较高（$12+/月）；PDFMathTranslate 免费开源，但 OCR 依赖 ONNX 模型，对复杂手写公式的识别不如 Mathpix
- 选择：预算充足 + 需要最高 OCR 质量选 Mathpix；预算有限 + 需要批量处理选 PDFMathTranslate
vs DeepL Pro 文档翻译
- 关系：替代。PDFMathTranslate 可以使用 DeepL 作为翻译引擎
- 区别：DeepL Pro 直接上传 PDF 翻译，使用简单但公式保留差；PDFMathTranslate 的公式保留能力远超 DeepL Pro
- 选择：普通文档翻译用 DeepL Pro；包含大量公式的学术论文必须用 PDFMathTranslate
vs MinerU
- 关系：上下游互补。MinerU 是 PDF 解析/提取工具（PDF → Markdown），PDFMathTranslate 是 PDF 翻译工具
- 区别：MinerU 不做翻译，PDFMathTranslate 做翻译。但 PDFMathTranslate 内部集成了 MinerU 作为复杂文档的解析后端
- 选择：需要提取 PDF 文本内容用 MinerU；需要翻译 PDF 用 PDFMathTranslate
场景选型决策树
需要翻译 PDF？
├── 只是普通文档（无公式）→ DeepL Pro / Google Translate
├── 学术论文（有公式）→ PDFMathTranslate
│ ├── 需要最高 OCR 精度 → Mathpix（付费）
│ └── 预算有限/需要批量 → PDFMathTranslate（免费）
├── 日常网页阅读 → 沉浸式翻译
└── 需要 PDF 转 Markdown → MinerU
第八章：真实应用场景
场景一：学术研究者翻译英文论文
痛点：CS/Math/Physics 领域的研究者需要大量阅读英文论文，公式密集、专业术语多，传统翻译工具会把公式搞乱。
落地方案：
pip install pdf2zh
pdf2zh paper.pdf -s openai -li en -lo zh
- 使用 OpenAI GPT-4o 翻译，对专业术语的准确度最高
- 输出双语对照版，方便对照原文验证
- 一次翻译只需 2-5 分钟（取决于论文长度和 API 速度） 价值：将论文翻译时间从 2-3 小时（手动）缩短到 5 分钟以内。
场景二：实验室批量翻译文献库
痛点：研究生或课题组积累了大量英文 PDF 文献，需要快速翻译整理。
落地方案：
pdf2zh --dir /path/to/literature/ -s deepl -li en -lo zh -o /path/to/output/ -t 4
--dir批量处理整个目录-t 4启用 4 线程并行翻译- DeepL 翻译质量稳定，适合长文档 价值：一键翻译整个文献库，配合 Zotero 插件可以直接在文献管理器中调用翻译。
场景三：企业技术文档翻译（本地部署）
痛点：企业的技术文档包含大量公式、架构图、代码块，不能上传到外部翻译平台（数据安全合规要求）。
落地方案：
# Docker 部署 + Ollama 本地模型（完全离线）
docker run -d -p 7860:7860 \
-v /data/docs:/docs \
byaidu/pdf2zh
# 或使用 Ollama 本地模型翻译
pdf2zh doc.pdf -s ollama -li en -lo zh
- 完全离线，数据不出内网
- Ollama + Qwen2/Llama3 可以实现零成本的本地翻译
- 满足金融、医疗等行业的合规要求 价值：零隐私风险 + 零 API 成本的文档翻译方案。
场景四：Zotero 文献管理器集成
痛点：研究者使用 Zotero 管理文献，需要在 Zotero 内直接翻译并阅读论文。
落地方案：安装 zotero-pdf2zh 插件：
- 在 Zotero 中右键论文 → "翻译 PDF"
- 自动调用 pdf2zh 翻译
- 翻译结果存储在 Zotero 库中 价值：将翻译能力无缝嵌入现有文献管理工作流。
场景五：AI Agent 通过 MCP 调用翻译
痛点：Claude Desktop / Cursor 等 AI Agent 需要翻译 PDF 文档，但自身无法处理 PDF 格式。
落地方案：
pdf2zh --mcp # STDIO 模式
- 通过 MCP 协议暴露翻译能力给 AI Agent
- Agent 可以自主决定何时调用翻译工具
- 适合构建"AI 研究助手"等应用 价值：让 AI Agent 具备处理学术 PDF 的能力，扩展 Agent 的工具箱。
第九章：工程落地
安装方式一览
方式一：pip 安装（最通用）
# Python 3.11-3.12
pip install pdf2zh
pdf2zh document.pdf
方式二：uv 安装（推荐）
pip install uv
uv tool install --python 3.12 pdf2zh
pdf2zh document.pdf
方式三：Docker 部署（最省心）
docker pull byaidu/pdf2zh
docker run -d -p 7860:7860 byaidu/pdf2zh
# 访问 http://localhost:7860/
方式四：Windows 桌面应用
从 Release 页面 下载 pdf2zh-version-win64.zip，解压双击 pdf2zh.exe。
方式五：Python API 集成
from pdf2zh import translate
translate(
input_path="paper.pdf",
output_dir="./output",
lang_in="en",
lang_out="zh",
service="openai",
envs={"OPENAI_API_KEY": "sk-xxx"}
)
常用命令速查
| 命令 | 作用 |
|---|---|
pdf2zh paper.pdf |
翻译（默认 Google 翻译，英→中） |
pdf2zh paper.pdf -s deepl |
使用 DeepL 翻译 |
pdf2zh paper.pdf -s openai |
使用 OpenAI 翻译 |
pdf2zh paper.pdf -s ollama |
使用本地 Ollama 模型 |
pdf2zh paper.pdf -li en -lo ja |
英→日 |
pdf2zh paper.pdf -p 1-5 |
只翻译第 1-5 页 |
pdf2zh paper.pdf -t 8 |
8 线程并行 |
pdf2zh paper.pdf --prompt terms.txt |
自定义术语提示词 |
pdf2zh paper.pdf --ignore-cache |
忽略翻译缓存 |
pdf2zh paper.pdf --compatible |
兼容模式（处理复杂 PDF） |
pdf2zh --dir ./papers/ |
批量翻译目录 |
pdf2zh -i |
启动 Web GUI |
pdf2zh -i --share |
启动 GUI 并生成公开链接 |
pdf2zh --mcp |
MCP Server 模式 |
pdf2zh --mode precise paper.pdf |
使用 v2.0 实验内核 |
环境变量配置
| 环境变量 | 用途 |
|---|---|
OPENAI\_API\_KEY |
OpenAI API 密钥 |
DEEPL\_API\_KEY |
DeepL API 密钥 |
AZURE\_API\_KEY |
Azure 翻译 API 密钥 |
HF\_ENDPOINT |
HuggingFace 镜像（解决模型下载问题） |
OLLAMA\_HOST |
Ollama 服务地址 |
关键依赖清单
| 依赖 | 版本 | 用途 |
|---|---|---|
| Python | 3.11-3.12 | 运行环境 |
| PdfMiner.six | — | PDF 结构解析 |
| PyMuPDF | — | PDF 读写和生成 |
| onnxruntime | — | DocLayout-YOLO 推理 |
| gradio | — | Web GUI |
| Go Noto Universal 字体 | — | 多语言字体支持 |
网络问题解决
国内用户下载 ONNX 模型可能失败，设置 HuggingFace 镜像：
# Windows CMD
set HF_ENDPOINT=https://hf-mirror.com
# PowerShell
$env:HF_ENDPOINT = "https://hf-mirror.com"
# Linux/macOS
export HF_ENDPOINT=https://hf-mirror.com
Docker 用户无需处理此问题，模型已内置在镜像中。
第十章：优缺点与局限
优点
| 优点 | 说明 |
|---|---|
| 公式保留出色 | YOLO 检测 + 跳过机制，公式几乎零损失 |
| 排版高度还原 | 原位替换策略，页面布局完整保留 |
| 翻译引擎灵活 | 10+ 种翻译后端可选，从免费到付费全覆盖 |
| 完全开源 | AGPL-3.0，代码透明，可审计可修改 |
| 多形态部署 | CLI/GUI/Docker/MCP/Zotero/HTTP API |
| 批量处理 | 支持目录级批量翻译 + 多线程 |
| 离线能力 | Ollama 后端实现完全离线翻译 |
| 学术背书 | EMNLP 2025 论文，经过学术同行评审 |
| 活跃社区 | 33k Stars、57 贡献者、3k Fork |
| 免费使用 | 核心功能完全免费（翻译 API 费用另计） |
缺点
| 缺点 | 说明 |
|---|---|
| 安装门槛 | 需要 Python 3.11-3.12 环境，对非技术用户不友好 |
| 首次加载慢 | ONNX 模型约 100MB，首次使用需下载 |
| OCR 能力有限 | 对扫描版 PDF 或手写公式的识别不如 Mathpix |
| 排版非完美 | 复杂双栏/三栏布局偶尔会有文字溢出 |
| 依赖翻译 API | 翻译质量取决于所选 API，工具本身不提升翻译质量 |
| 中文排版适配 | 中文字符宽度与英文不同，长句可能超出文本框 |
| v2.0 尚不稳定 | 实验版内核未经过大规模验证 |
局限性
- 扫描版 PDF：如果 PDF 是图片扫描件（非文字层 PDF），需要先 OCR 处理，PDFMathTranslate 本身的 OCR 能力有限
- 手写公式：对手写数学公式的识别准确率较低，建议先用 Mathpix OCR 处理
- 极复杂排版：多栏 + 浮动图 + 脚注 + 侧边栏的复杂布局偶尔会出现错位
- 翻译质量：工具不改进翻译质量，如果用 Google 翻译，专业术语的准确性不如人工翻译
- 大文件性能：超过 100 页的 PDF 翻译时间较长，需要合理设置线程数
不建议使用的场景
- 需要出版级翻译质量的场景（建议人工翻译 + 专业排版）
- PDF 内容以图片为主的场景（扫描版书籍）
- 对翻译速度有极高要求的实时场景（这是离线批处理工具）
- 完全不懂技术的非技术用户（虽然有 GUI，但配置 API Key 仍有门槛）
第十一章：常见误区
误区一："PDFMathTranslate 自带了翻译能力"
错误。PDFMathTranslate 本身只是一个"管线工具"，负责解析 PDF、分类元素、调用翻译 API、回填文本。翻译能力完全来自第三方 API（Google / DeepL / OpenAI 等）。选择不同的翻译引擎，翻译质量会有显著差异。
误区二："安装了 PDFMathTranslate 就能离线翻译"
部分错误。默认使用 Google 翻译，需要联网。只有配置 Ollama 本地模型后才能完全离线翻译。离线翻译的质量取决于本地模型的翻译能力（Qwen2 / Llama3 等大模型的中英翻译质量不如 GPT-4o 或 DeepL）。
误区三："它能完美保留所有 PDF 的排版"
错误。虽然原位替换策略的排版保留率很高（90%+ 场景表现优秀），但不是 100% 完美。复杂的多栏布局、浮动图表、超大表格等边缘情况下仍可能出现轻微错位。
误区四："它和 DeepL / Google Translate 的文档翻译功能一样"
错误。核心差异在于公式保护。DeepL 和 Google Translate 的文档翻译会把公式当作普通文本处理，导致公式消失或乱码。PDFMathTranslate 通过 YOLO 模型检测并跳过公式区域，这是它最大的差异化优势。
误区五："v2.0 比 v1.9 更好，应该直接用 v2.0"
需谨慎。v2.0 目前仍是实验版本（--mode precise），官方描述为"不解决兼容性问题，不面向社区贡献"。对于稳定使用场景，建议继续使用 v1.9.x。v2.0 适合愿意承担风险、需要更高质量翻译的用户。
误区六："Docker 部署一定比本地安装好"
看场景。Docker 的优势是零配置、环境隔离，但缺点是镜像体积大（约 2-3GB）、GPU 加速需要额外配置、调试不便利。如果是个人使用，pip 安装更灵活；如果是服务器部署或多用户共享，Docker 更合适。
误区七："所有翻译服务的翻译质量差不多"
差距很大。在学术翻译场景下，GPT-4o / Claude / DeepL 的专业术语准确度显著高于 Google Translate / Bing 翻译。建议对翻译质量有要求的场景使用付费 API（DeepL 或 OpenAI）。
第十二章：学习路径
阶段一：快速上手（30 分钟）
目标：能翻译一篇简单的英文论文
- 安装：
pip install pdf2zh - 翻译：
pdf2zh paper.pdf - 查看输出：
paper-mono.pdf和paper-dual.pdf - 尝试 GUI：
pdf2zh -i - 尝试指定翻译服务：
pdf2zh paper.pdf -s openai关键知识点：
- 基本命令行用法
- 输出文件命名规则
- 翻译服务的选择
阶段二：深入配置（1-2 小时）
目标：能针对不同场景选择最优配置
- 学习高级参数：
-p（部分翻译）、-t（多线程）、-f（正则过滤） - 配置翻译 API Key（OpenAI / DeepL）
- 自定义提示词（
--prompt） - 批量翻译（
--dir） - 配置文件使用（
--config） 关键知识点：
- API Key 的配置方式（环境变量 vs 命令行参数）
- 翻译缓存机制（避免重复调用 API）
- 兼容模式（
--compatible）的使用时机
阶段三：部署与集成（2-4 小时）
目标：能在服务器上部署并与其他工具集成
- Docker 部署（
docker-compose.yml） - 云平台一键部署（Zeabur / Sealos / Koyeb）
- Zotero 插件安装和配置
- MCP Server 配置
- Python API 集成到自己的项目 关键知识点：
- Docker 网络和端口映射
- MCP 协议基础
- Python API 的参数和返回值
阶段四：原理深入（可选，适合开发者）
目标：理解内部实现，能贡献代码
- 阅读
converter.py理解完整管线 - 研究 PdfMiner 的 PDF 解析原理
- 了解 DocLayout-YOLO 的模型结构和推理过程
- 研究文本原位替换的技术细节
- 阅读论文：EMNLP 2025 论文全文 关键知识点：
- PDF 内部结构（对象树、内容流、文本操作符）
- ONNX 模型推理流程
- PyMuPDF 的文本替换 API
- 多线程翻译调度策略
阶段五：高级定制（高级用户）
目标：能开发自定义翻译后端或扩展功能
- 开发自定义翻译服务（实现 Translator 接口）
- 修改 DocLayout-YOLO 模型（自定义检测类别）
- 开发自定义字体处理策略
- 贡献代码到上游仓库
第十三章：必须记住的重点
10 个必记知识点
- 本质是管线工具：PDFMathTranslate 不发明翻译算法，只做 PDF 解析 → 元素分类 → API 调用 → 原位回填的管线编排
- 公式保护靠 YOLO：DocLayout-YOLO 检测模型是公式保护的基石，它区分文本和公式区域，翻译时跳过公式
- 原位替换而非重排：不是重新生成 PDF，而是在原始 PDF 的文本操作符中精确替换字符串，这是排版高度还原的关键
- 翻译质量取决于 API：选择 GPT-4o / DeepL / Claude 得到专业级翻译，选择 Google / Bing 得到通用级翻译
- 两种输出模式：
-mono.pdf是纯译文版，-dual.pdf是双语对照版，后者更适合学术研究对照阅读 - 完全离线方案：Ollama + 本地大模型 = 零 API 成本 + 零隐私风险的翻译方案
- v1.9 是稳定版，v2.0 是实验版：生产环境用 v1.9.x，v2.0 有更好的跨栏/跨页处理但兼容性不保证
- 首次运行需下载模型：DocLayout-YOLO ONNX 模型约 100MB，Docker 镜像已内置，pip 安装首次会自动下载
- 多形态部署：CLI / GUI / Docker / MCP / Zotero / HTTP API 六种使用方式，覆盖从个人到团队到 AI Agent 的全部场景
- EMNLP 2025 学术背书：这不是一个玩具项目，而是经过学术同行评审的研究成果，有论文有引用有 33k 社区验证
第十四章：总结
学习笔记版
定义：开源 PDF 科学文档翻译工具，翻译全文同时保留公式、图表、排版。
核心管线：PDF 解析（PdfMiner）→ 布局检测（DocLayout-YOLO）→ 文本翻译（可插拔 API）→ 原位回填（PyMuPDF）。
关键创新：公式保护（YOLO 检测 + 跳过翻译）、原位替换（不重新生成 PDF）、翻译引擎解耦（10+ 种后端）。
使用方式：
pip install pdf2zh→pdf2zh paper.pdf→ 输出paper-mono.pdf+paper-dual.pdf。选型建议：有公式 → PDFMathTranslate；无公式 → DeepL Pro / Google；最高 OCR → Mathpix；离线 → Ollama + pdf2zh。
版本策略：v1.9.x 稳定版（推荐），v2.0 实验版（更高质量但不保证兼容）。
部署方式：CLI / GUI / Docker / MCP / Zotero 插件 / HTTP API。
信息来源：
- GitHub 仓库：https://github.com/PDFMathTranslate/PDFMathTranslate
- EMNLP 2025 论文：https://aclanthology.org/2025.emnlp-demos.71/
- 官方在线服务：https://pdf2zh.com/
- 沉浸式翻译 BabelDOC：https://app.immersivetranslate.com/babel-doc/
- Zotero 插件：https://github.com/guaguastandup/zotero-pdf2zh