PDFMathTranslate（pdf2zh）快速上手：两条命令翻完 PDF 论文，公式与双栏排版原样保留-迪斯科星球

PDFMathTranslate（pdf2zh）快速上手：两条命令翻完 PDF 论文，公式与双栏排版原样保留

【免费下载链接】PDFMathTranslate[EMNLP 2025 Demo] PDF scientific paper translation with preserved formats - 基于 AI 完整保留排版的 PDF 文档全文双语翻译，支持 Google/DeepL/Ollama/OpenAI 等服务，提供 CLI/GUI/MCP/Docker/Zotero项目地址: https://gitcode.com/GitHub_Trending/pd/PDFMathTranslate

PDFMathTranslate 提供的命令行工具 pdf2zh，专门做 PDF 论文的双语翻译：文字译成中文，公式、图表和双栏排版照旧，默认服务不用配密钥。读外文文献的学生和研究人员，用它几分钟就能拿到一份可读的中文对照版。

先看清产物：pdf2zh 翻译后你会拿到什么

对document.pdf跑一遍pdf2zh，当前目录会多出两份文件：

document-mono.pdf：纯译文版，通篇是翻译后的内容
document-dual.pdf：中英对照版，原文与译文同页并排

对照效果上，正文里的公式、插图、目录、双栏结构一个不缺，图编号、脚注、页眉也都留在原位。

两分钟跑起来：安装 pdf2zh 并得到第一份译文

整个过程就两条命令：

pip install pdf2zh

pdf2zh document.pdf

默认使用 Google 翻译服务，不用申请任何密钥。第一次运行会下载 ONNX 版面模型（ONNX 是一种可以在本地直接运行的模型文件格式），所以比之后每次都要慢一些，属于正常现象。跑完后，上一节说的两份产物就落在当前目录。

三步管线拆解：公式、图表、双栏为什么一个不丢

把它理解成一位面对已排版校样的老校订员，分三步走：

版面模型逐页扫描，把公式、图片、表格、目录统统圈出来，标记为"不能碰"；
只有文字块被单独摘出来，送到翻译服务，其余部分纹丝不动；
译好的文字按原字体、原位置填回原来的位置，版式因此毫发不伤。

版面检测这一步的实现在 pdf2zh/doclayout.py，想抠细节可以直接读。

五种使用场景对号入座：单篇、批量、GUI、Docker、MCP

单个文件：pdf2zh paper.pdf，一条命令，产物直接出现在当前目录。

批量目录：pdf2zh --dir /path/to/papers/ -o results/，整个目录的 PDF 一次翻完，输出统一归到-o指定的目录。

Web 图形界面：pdf2zh -i，然后浏览器打开http://localhost:7860/，在服务配置、页码选择、实时预览之间点点就行。

Docker 部署：

docker pull byaidu/pdf2zh docker run -d -p 7860:7860 byaidu/pdf2zh

同样是 7860 端口的 Web 界面，适合固定跑在服务器上。

MCP 接入：pdf2zh --mcp（MCP 即模型上下文协议，给 AI 助手挂外部工具的方式）。注册进 Claude Desktop 后，对话里丢一个 PDF 就能直接翻，配置示例见 docs/ADVANCED.md。

pdf2zh 参数速查表：日常常用的 8 个

参数	作用	短示例
`-p`	指定页码	`pdf2zh paper.pdf -p 1-3,5`只翻第 1–3 页和第 5 页
`-s`	换翻译服务	`-s deepl`、`-s openai:gpt-4o-mini`
`-li`/`-lo`	源语言 / 目标语言	`-li en -lo zh`
`-t`	翻译线程数	`-t 4`开四线程并发
`-o`	输出目录	缺省为当前目录，`-o results/`
`--ignore-cache`	忽略翻译缓存，强制重翻	加在任意命令后
`--prompt`	加载自定义 LLM 提示词文件	`--prompt my_prompt.txt`
`--config`	加载 JSON 配置文件	`--config config.json`

环境前置条件：Python 版本、网络与 Windows 运行库

Python 必须是 3.11 或 3.12：项目声明>=3.11,<3.13，3.10 和 3.13 都不行。
需要联网：首次运行要从 Hugging Face 拉取wybxc/DocLayout-YOLO-DocStructBench-onnx版面模型，断网会卡住。
依赖不用手装：onnxruntime、pdfminer、gradio 等会随pip install自动带入。
Windows 用户如果跑 exe 版本报 DLL 加载失败，先装 VC++ 2015–2022 运行库。

报错对照清单：三个高频问题怎么解

扫描版 PDF 翻不动：纯图片扫描件没有文本层，而 pdf2zh 读的就是文本层，取不到任何内容。先用 OCR（光学字符识别，把图片里的字还原成可选中文字）生成文本层，再投入翻译。

模型下载卡住：部分地区访问 Hugging Face 受限，运行前先设镜像：

set HF_ENDPOINT=https://hf-mirror.com

PowerShell 里写$env:HF_ENDPOINT = https://hf-mirror.com。

切换服务后报鉴权错误：对应服务的密钥环境变量没有预设，比如DEEPL_AUTH_KEY、OPENAI_API_KEY。各服务对应哪个变量名，查 docs/ADVANCED.md 里的表格，设好再执行。

想要"翻 PDF 还保住排版"，装pdf2zh两条命令就能交付；其余参数与配置细节，翻 docs/ADVANCED.md 就有答案。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析