PDF 翻译工具 PDFMathTranslate 使用指南：外文论文秒变排版原样的中文版-开发者社区

PDF 翻译工具 PDFMathTranslate 使用指南：外文论文秒变排版原样的中文版

【免费下载链接】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）是一款 AI 驱动的PDF 翻译工具，专门处理科学论文这类"排版命根子"文档——公式、图表、目录、注释全部留在原位，只把文字换成目标语言。它支持 Google、DeepL、OpenAI、Ollama 等 20 多种翻译服务，用法有 3 种：本地图形界面、Docker 共享部署、命令行脚本自动化。下面按你的使用场景直接给命令，照抄就能跑。

图里是一次真实运行的全过程：拖入英文 PDF，选翻译服务，几分钟后得到中文版。左右两栏是同一页的原稿与译文，对比一下就知道值不值得继续往下看。

本地一键翻译外文 PDF

适合：一个人、一台机器，不想装多余东西。前置条件只有一个——Python 版本在 3.11–3.12 之间。

安装只要一行：

pip install pdf2zh

这条命令把翻译工具连同依赖全部装好，装完终端里多出一个pdf2zh命令。

然后看你喜欢哪种操作方式：

图形界面派。敲下面这条命令，它会启动一个本地 Web 服务：

pdf2zh -i

浏览器一般会自动弹出；没弹的话手动访问http://localhost:7860，把 PDF 拖进去、选好服务、点翻译，完事。

命令行派。翻译一篇论文就一句：

pdf2zh your_document.pdf

跑完后当前目录会多出两个文件：your_document-mono.pdf（纯译文）和your_document-dual.pdf（中英对照版）。想换翻译服务加一个参数，比如pdf2zh your_document.pdf -s deepl。

提示：如果默认用的 Google 服务访问不畅，换-s bing或-s deeplx这类不需要 Key 的服务即可，服务清单见 docs/ADVANCED.md。

团队共享部署 PDF 翻译服务

适合：实验室、课题组、公司团队。目标是"服务器装一次，全组用浏览器"，没人需要在本地碰 Python。

官方 Docker 镜像两条命令搞定：

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

第一条拉镜像，第二条在后台启动容器并把本机 7860 端口映射出去。之后团队成员打开http://服务器IP:7860就是上面那个图形界面，开箱即用。

如果容器里默认的翻译服务不好使，用--env注入密钥即可，例如docker run -d -p 7860:7860 -e DEEPL_AUTH_KEY=你的Key byaidu/pdf2zh。想给组员设账号密码，加--authorized users.txt参数（格式见 docs/ADVANCED.md），不用改任何仓库文件。

脚本自动化接入批量文献处理

适合：要把翻译嵌进数据流水线、定时任务或者自己写的程序。

批量翻整个目录，一条命令：

pdf2zh --dir /path/to/your/papers/

目录里每个 PDF 都会生成对应译文，天然适合写进 cron 或 Makefile。

Python API可以直接调库，不用起进程：

from pdf2zh import translate params = {'lang_in': 'en', 'lang_out': 'zh', 'service': 'google', 'thread': 4} (file_mono, file_dual) = translate(files=['example.pdf'], **params)

拿到两个文件路径，后续处理（归档、上传、发邮件）全由你的脚本说了算。

HTTP API则把翻译服务变成远程接口：装pip install pdf2zh[backend]后跑pdf2zh --flask，就能向http://localhost:11008/v1/translate提交任务、查进度、下载结果，详细协议见 docs/APIS.md。

它凭什么做到公式不飞

原理只讲三句：翻译前先用一个版式检测模型（DocLayout-YOLO）扫描每页结构，把公式、图表、表格划成"保护区"整体跳过；只对普通正文送翻译服务；译文按原文坐标和字号原位回填。所以输出 PDF 的骨架和输入几乎一模一样——这也是"PDF 翻译"和"把 PDF 转成 Word 再翻译"路线的本质区别。

另外还有个值得知道的模式：--mode precise会调用 v2.0 翻译内核（独立环境，跨页语义一致性更好），fast模式（默认）则更稳更快，见 docs/ADVANCED.md。

高频进阶参数速查

想解决什么	命令	说明
复杂排版翻不动、报错	`pdf2zh file.pdf --compatible`	兼容模式，牺牲一点效果换成功率
大文件太慢	`pdf2zh file.pdf -t 4`	4 个线程并行翻译
只翻摘要前 5 页	`pdf2zh file.pdf -p 1-5`	页码区间翻译
换翻译服务	`pdf2zh file.pdf -s ollama`	Ollama 本地模型，数据不出内网
指定语言方向	`pdf2zh file.pdf -li en -lo ja`	英译日，语言代码见官方文档
固定翻译风格	`pdf2zh file.pdf --prompt prompt.txt`	给 LLM 类服务喂自定义提示词
术语、字体等长期配置	`pdf2zh file.pdf --config config.json`	默认读取`~/.config/PDFMathTranslate/config.json`
GUI 端口冲突	`pdf2zh -i --serverport 8080`	默认端口是 7860，换个数字即可
扫描件页面无文字	`pip install 'pdf2zh[ocr]'`	可选 OCR 扩展，自动识别纯图片页

参数背后的细节（每个翻译服务要配的环境变量、例外字体正则、缓存策略）都在 docs/ADVANCED.md，按上面表格找到参数名去查对应小节就行。

常见坑自查

Q：首次运行卡在模型下载、报网络错误？程序要拉一个版式检测模型（wybxc/DocLayout-YOLO-DocStructBench-onnx），国内网络建议先切镜像再启动：

export HF_ENDPOINT=https://hf-mirror.com && pdf2zh -i

Windows PowerShell 用户写成$env:HF_ENDPOINT = "https://hf-mirror.com"即可。

Q：某篇 PDF 翻译中途失败或版面错乱？别硬刚，先切兼容模式跑一遍：

pdf2zh complex_document.pdf --compatible

Q：同一文档翻过之后改动无效，像被"缓存"住了？程序有翻译缓存加速，强制绕开它：pdf2zh file.pdf --ignore-cache。

Q：GUI 打不开，提示端口占用？默认 7860 被占时换一个：pdf2zh -i --serverport 8080。

Q：Windows 双击下载的 exe 打不开？装一下微软的 VC 运行库（vc_redist.x64）再试，这是 Windows 打包版的常见前置。

延伸资源

完整参数与全部翻译服务清单：docs/ADVANCED.md
Python / HTTP 两种 API 的二次开发参考：docs/APIS.md
图形界面详细说明：docs/README_GUI.md
代理网络环境配置：docs/PROXY_CONFIGURATION.md
命令行核心逻辑源码：pdf2zh/pdf2zh.py
社区参与规范：docs/CODE_OF_CONDUCT.md

下一步，从哪开始

今天就能做完的事：装好pip install pdf2zh，挑一篇最近在啃的外文论文跑pdf2zh 你的论文.pdf，对照生成的-dual.pdf双语版，判断翻译质量是否符合你的要求——不满意就换-s再试一两个服务，五分钟能试完。
本周可以规划的事：如果你身边有人也需要，把 Docker 版部署到一台常开的机器上，把http://服务器IP:7860的链接发给全组，从此大家都不用各自折腾环境。

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