PDFMathTranslate 入门教程：保版式 PDF 翻译，公式图表不动，免 API key-二趣网

PDFMathTranslate 入门教程：保版式 PDF 翻译，公式图表不动，免 API key

【免费下载链接】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 翻译：它读取带文本层的 PDF，用 ONNX 版面模型逐块认出正文、公式、图和图注，只把需要翻译的文字发给翻译服务，再把译文写回原位，产出纯中文版和中英对照版各一份。适合读论文、做文献综述，也要批量 PDF 翻译整个文件夹的人。

用之前先想清楚的三个问题

我的 PDF 能不能翻？

能翻的前提是文件带文本层，鼠标选中正文能复制出来就合格。扫描版、图片型 PDF 不适用，要先 OCR 成可复制文本的 PDF 再翻；仓库也提供了实验性 OCR 扩展pip install 'pdf2zh[ocr]'，可对纯图片页自动跑本地 OCR。

我要不要先准备 API key？

不用。默认服务google免 key，bing同样免 key，装完直接能跑；deepl、openai这类服务要先配环境变量，各服务要设哪些变量见 docs/ADVANCED.md 里的对照表；ollama可走本地模型，翻译环节不依赖外网。

跑一遍要花多少功夫？

装完一条命令出结果。pip install pdf2zh之后执行pdf2zh paper.pdf，等翻译完成，当前目录就多两个文件；首次运行会先下载版面模型，多等一会儿属正常现象。

从安装到第一份输出

先装包，要求 Python 3.11 或 3.12：

pip install pdf2zh

把要翻的 PDF 放进当前目录，执行：

pdf2zh paper.pdf

✅ 翻译完成后，你会在原地找到两份产物：

paper-mono.pdf：纯中文版
paper-dual.pdf：中英双语对照版

习惯uv的话，用uv tool install --python 3.12 pdf2zh代替 pip 安装；Windows 不想装 Python，可下载官方发布的pdf2zh-version-win64.zip，解压后直接运行pdf2zh.exe。

命令组合速查

常用场景的参数都收在这张表里：

使用场景	命令/参数	说明
指定语言方向	`-li en -lo zh`	默认就是英译中，其他方向显式指定
只翻部分页	`-p 1-5`	长文档先试读前几页，重复内容靠缓存不重复调 API
切换翻译服务	`-s deepl`、`-s openai`、`-s ollama`	google/bing 免 key，其余先配环境变量，见 docs/ADVANCED.md
固定术语	`--prompt prompt.txt`	模板支持`${lang_in}`、`${lang_out}`、`${text}`三个变量
批量 PDF 翻译	`--dir papers/ -o output/ -t 3`	整目录处理；`-t`设翻译线程数，`-o`指定输出目录
浏览器图形界面	`pdf2zh -i`	没自动弹出就访问`http://localhost:7860/`，详见 docs/README_GUI.md
Docker 部署	`docker pull byaidu/pdf2zh`	再执行`docker run -d -p 7860:7860 byaidu/pdf2zh`，团队共用一个入口

怎么确认译文靠谱

先看官方演示：仓库 docs/ 里放了一篇双栏、多公式、带网络图的论文翻译前后截图，正文换成了中文，公式、网络图、图注都留在原位。

还有三个可自行核实的事实：

项目论文被 EMNLP 2025 System Demonstrations 接收，摘要中写明 PyPI 累计下载量已超过 22 万次；
核心代码都在 pdf2zh/ 包内，版面解析看pdfinterp.py（约 360 行）、翻译调度看translator.py（约 1200 行），能顺下来读；
Python API 目前处于弃用状态、计划在 2.0 重新提供，需要程序化调用的先看 docs/APIS.md 的说明。

避坑清单

⚠️ 遇到问题按「症状 → 原因 → 解法」对号入座：

翻译卡住、输出空白 → 输入是扫描版或图片型 PDF，没有文本层可解析 → 先 OCR 成可复制文本的 PDF 再翻。
首次运行一直卡住或超时 → 程序在下载版面模型wybxc/DocLayout-YOLO-DocStructBench-onnx，网络不畅 → 先设镜像变量再运行：

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

其他网络问题查 docs/PROXY_CONFIGURATION.md。 3. 换了服务或提示词，译文却没变 → 翻译结果有缓存，相同内容不会重翻 → 加--ignore-cache强制重翻。 4. 输出 PDF 字体显示异常 → 默认做了字体子集化以压缩体积，个别阅读器不兼容 → 加--skip-subset-fonts跳过字体子集化。

说到底，PDFMathTranslate 只干一件具体的事：把文字换成中文，公式、图表和版式保持原样。在读论文的人，今天装完跑一条命令，就能拿到第一份dual对照文件；要给团队搭共用工具的人，起一个 Docker 实例，让大家从浏览器进；想弄明白实现的人，从 pdf2zh/ 目录读起，整条链路读起来并不长。

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

企业官网建设流程全解析