PDFMathTranslate/PDFMathTranslate · 上手攻略

仓库：PDFMathTranslate/PDFMathTranslate
链接：https://github.com/PDFMathTranslate/PDFMathTranslate
分类：academic-writing · agent（PDF translation · scientific documents · layout preservation）
作者：Jay
更新：2026-07-12

这是什么

PDFMathTranslate（发布名 pdf2zh）是一个保留排版的 PDF 学术论文翻译工具，能将 PDF 文档完整翻译为双语格式（原文+译文对照）或纯译文，同时保留公式、图表、目录结构、注释等复杂元素不走形。

核心特点： - 支持 Google、DeepL、OpenAI、Claude、Ollama、MiniMax 等多种翻译服务 - 提供 CLI、GUI、Docker、Zotero 插件多种使用方式 - 被 EMNLP 2025 收录为 Demo 论文 - v2.0（2026年）已迁移至 PDFMathTranslate/PDFMathTranslate-next

⚠️ 重要提醒：v2.0 已发布并迁移至新仓库 PDFMathTranslate/PDFMathTranslate-next，新用户建议直接使用 v2 版本（见下文）。

解决什么问题

论文翻译格式崩溃：大多数翻译工具处理数学公式、表格、图表时会乱码或丢失；PDFMathTranslate 针对学术 PDF 结构专门处理，保持版式完整
翻译服务分散：有时 Google 翻译效果好，有时 DeepL 更准确；工具内置多服务支持，可随时切换对比
批量翻译需求：CLI 模式支持批量处理一个目录或多个链接，适合研究团队系统性翻译文献库
不想装任何东西：提供在线 demo（pdf2zh.com），打开即用，无需配置 Python 环境

快速安装

方式一：在线 Demo（零安装，推荐尝鲜）

pdf2zh.com — 公开免费服务（推荐）
HuggingFace Demo
ModelScope Demo

公开 demo 算力有限，请勿滥用。

方式二：Python pip 安装（本地）

# Python 版本要求：3.11 ≤ version ≤ 3.12

# 推荐用 uv 安装（更快）
pip install uv
uv tool install --python 3.12 pdf2zh

# 或直接 pip
pip install pdf2zh

# 翻译当前目录下的 PDF（生成 example-mono.pdf 和 example-dual.pdf）
pdf2zh document.pdf

# 交互式 GUI（浏览器打开）
pdf2zh -i
# 然后访问 http://localhost:7860

⚠️ 如果遇到模型下载慢（依赖 wybxc/DocLayout-YOLO-DocStructBench-onnx），设置镜像： ```bash

Windows PowerShell

$env:HF_ENDPOINT = "https://hf-mirror.com"

Linux/macOS

export HF_ENDPOINT=https://hf-mirror.com ```

方式三：Windows exe（绿色版，无需 Python）

从 Release 页面下载 pdf2zh-{版本}-win64.zip
解压，双击 pdf2zh.exe 运行
浏览器访问 http://localhost:7860

Windows 运行报错：如果双击后无反应，需先安装 vc_redist.x64.exe。

方式四：Docker（适合服务器部署）

# 标准版（SearxNG 内置）
docker pull byaidu/pdf2zh
docker run -d -p 7860:7860 byaidu/pdf2zh
# 访问 http://localhost:7860

# 或 GitHub Container Registry（Docker Hub 访问受限地区）
docker pull ghcr.io/byaidu/pdfmathtranslate
docker run -d -p 7860:7860 ghcr.io/byaidu/pdfmathtranslate

方式五：Zotero 插件

安装 zotero-pdf2zh 插件，在 Zotero 内直接翻译 PDF，无需离开文献管理界面。

核心用法

基础命令行翻译

# 翻译本地文件
pdf2zh ~/paper.pdf

# 翻译在线 PDF（URL）
pdf2zh https://example.com/paper.pdf

# 批量翻译（目录）
pdf2zh ~/papers/

# 指定翻译服务（默认 Google）
pdf2zh --service deepL document.pdf

# 生成双语对照版（默认行为，生成 -mono.pdf 和 -dual.pdf）
# -mono.pdf：纯译文
# -dual.pdf：原文+译文左右对照

# 精确模式（v2.0 隔离环境，更准确但更慢）
pdf2zh --mode precise document.pdf

支持的翻译服务

服务	配置方式	说明
Google	无需 API Key（默认）	免费，速率限制
DeepL	需要 API Key	翻译质量高
OpenAI	需要 API Key + `OPENAI_API_KEY`	GPT 系列
Claude	需要 API Key + `ANTHROPIC_API_KEY`	Anthropic 模型
Ollama	本地运行，无 API 费用	完全离线
MiniMax	需要 API Key	国产模型

GUI 交互模式

pdf2zh -i
# 浏览器打开 http://localhost:7860

界面支持： - 拖拽上传 PDF - 选择翻译服务 - 实时预览翻译结果 - 下载双语/单语 PDF

高级选项（部分）

参数	功能
`--mode precise`	v2.0 精确翻译模式，隔离环境运行
`--service`	指定翻译服务
`--lang`	目标语言（默认自动检测）
`--output`	指定输出目录
`--parallel`	并行翻译页数（加速，但费用增加）

v2.0 新版（PDFMathTranslate-next）

v2.0 已于 2026 年发布，主要改进： - 隔离翻译内核：避免依赖冲突，提高翻译稳定性 - 精确模式：--mode precise 提供更高质量的翻译结果 - 新仓库：PDFMathTranslate/PDFMathTranslate-next

新用户建议直接使用 v2 版本，v1 仓库不再活跃开发。

典型适用场景

场景	用法
翻译 arXiv 论文	CLI 一行命令批量处理整个文件夹，半天翻译几十篇
中英双语对照阅读	生成 `-dual.pdf`，左侧英文原文右侧中文翻译，适合论文精读
论文初筛	快速翻译摘要和目录，判断论文是否值得深入阅读
文献管理流程集成	Zotero 插件直接在阅读器内翻译，无需切换工具
服务器自动化翻译	Docker 部署到云服务器，API 化批量处理

坑与注意

v2.0 已发布：当前仓库（PDFMathTranslate/PDFMathTranslate）已不再活跃开发，新功能在 PDFMathTranslate-next，请优先使用新版
网络问题（国内用户）：首次运行需下载 DocLayout-YOLO 模型，HF_ENDPOINT 设置镜像可解决
Python 版本限制严：仅支持 Python 3.11–3.12，其他版本会报错（建议用 uv 安装指定版本）
翻译质量依赖模型：Google 免费翻译质量一般，复杂数学公式建议使用 Claude / GPT / DeepL 等付费服务
版权问题：翻译受版权法约束，仅用于个人学习研究，不要大规模商业分发翻译后的论文
大型 PDF 内存占用：几百页的论文翻译需要较大内存，GUI 模式长时间跑可能内存溢出
公式渲染不完全：极少数特殊字体或手写公式可能渲染不完全，翻译后建议人工核对关键公式

与同类对比

工具	定位	优势	劣势
PDFMathTranslate	保留公式排版的论文翻译	公式/表格保留完整、CLI 强大、EMNLP 认证	v1 已停更、v2 在新仓库
Immersive Translate	通用网页/文档翻译	浏览器插件形式、中文体验好、实时翻译	PDF 处理不如专业工具
DeepL Write	文档翻译	翻译质量高	无法保留公式排版
Calibre + 翻译插件	电子书翻译	功能多、生态完整	公式处理弱、配置复杂
ChatGPT PDF 对话	通用 AI 翻译	可交互、上下文理解好	无批量能力、公式支持差

一句话结论

PDFMathTranslate 是学术论文翻译的最佳本地工具——公式表格原样保留、CLI 强大适合批量处理、GUI 零门槛直接用；唯一需要注意的是新版 v2 已迁至新仓库，老仓库不再维护，新用户请直接用 PDFMathTranslate-next。

来源：GitHub README（PDFMathTranslate/PDFMathTranslate）、pdf2zh.com、GitHub Release、EMNLP 2025