BabelDOC：把 PDF 翻译时保住公式和排版这件事讲清楚-平芜编程栈

BabelDOC：把 PDF 翻译时保住公式和排版这件事讲清楚

【免费下载链接】BabelDOCYet Another Document Translator项目地址: https://gitcode.com/GitHub_Trending/ba/BabelDOC

BabelDOC 是一个开源 PDF 翻译工具：给它一份英文论文 PDF，还你一份中文版，公式、表格、多栏排版都留在原位。适合需要批量处理论文和技术文档、又不想手动重排版的人。

🎯 它先解决了三个问题

文字一抽出来，排版就散了

普通工具只会把 PDF 里的文字抽成纯文本去翻译，贴回去之后栏序错乱、标题错位，基本要手动重排。BabelDOC 先把 PDF 解析成中间语言表示（IL），记录每个字的位置、字体和段落关系，翻译完再按原排版重新铺回去。

公式会被翻译搅乱

数学符号和公式是翻译中最容易坏的部分，当成普通文本处理必然乱码。BabelDOC 通过字体和字符模式识别公式区域，把它当占位符原样保留，不参与翻译。

术语翻译前后不一致

同一个词每次翻出不同译法，读论文的人会很痛苦。BabelDOC 有两条路：手动导入术语 CSV，或者在翻译时自动从文档里提取高频术语（默认开启）。

它提供三种用法：

用法	适合谁	说明
命令行	开发者、自动化脚本	参数灵活，支持多文件批量
Python 库	想嵌入自己程序的人	定位为内部 API，稳定性不保证
在线服务	普通用户	免安装，浏览器里直接跑

🚀 5 分钟跑通第一条命令

先用 uv 装好（如果还没装），然后一条命令安装 BabelDOC：

uv tool install --python 3.12 BabelDOC

装完直接跑一条翻译命令。注意它必须配一个 OpenAI 兼容的 LLM 才能工作，本地模型（比如 Ollama）也可以，API key 随便填：

babeldoc --files example.pdf \ --lang-in en --lang-out zh \ --openai --openai-model gpt-4o-mini \ --openai-base-url https://api.openai.com/v1 --openai-api-key sk-xxx

几个关键参数：--files指定输入 PDF（可多次传入批量处理）；--lang-in/--lang-out指定源语言和目标语言，默认就是英文翻中文；--openai一组参数指定翻译模型。

跑完后终端会显示进度条，输出目录里会出现两份 PDF：一份原文译文对照的双语版，一份纯译文版。

📄 真实场景怎么用

翻译带公式的论文

论文是最典型的场景：有公式、有术语、篇幅长。配上术语库和分块：

babeldoc --files paper.pdf --glossary-files glossary.csv --max-pages-per-part 50

术语 CSV 需要source、target、tgt_lng三列，文件名会作为术语表名字出现在给模型的提示词里
--max-pages-per-part把长文档切块翻译、完成后自动合并，长文档必加

只翻大文档的特定几页

想先看某几页效果，或者只需要附录部分：

babeldoc --files large.pdf --pages 1,3,5-10 --only-include-translated-page

--pages支持1,2,1-,-3,3-5这类写法；--only-include-translated-page只在输出里保留翻译过的那几页，配合--pages使用。

处理扫描件

扫描 PDF 翻完会出现"原文+译文"重影，因为底图上本来就印着文字：

babeldoc --files scanned.pdf --auto-enable-ocr-workaround

系统检测到扫描件比例较高时会自动启用 OCR 处理并跳过后续扫描检测。前提是黑字白底；如果你已经确认是扫描件，也可以直接用--ocr-workaround让译文下方垫白色底块盖住原文。

⚙️ 参数调优：只看这四个

--qps：翻译 API 的每秒请求数上限，默认 4。API 额度宽裕就调高，频繁被限流就调低。

--pool-max-workers：内部任务池的线程数，不指定时跟随--qps。API 不卡的话适当调大能提速。

--max-pages-per-part：每个分块的页数。100 页以上的文档建议设 30~50，能明显缓解内存压力，翻译完自动合并。

缓存与术语：相同文本重复翻译会自动命中缓存，想强制重翻加--ignore-cache。术语表 CSV 建议单独维护、长期复用，比每次依赖自动提取更稳。

🛠️ 遇到问题先看这里

现象	大概率原因	怎么处理
翻译很慢	文档大或 API 慢	加`--max-pages-per-part`分块，调`--qps`
输出的 PDF 某些阅读器打开排版错乱	PDF 结构复杂、兼容性问题	加`--enhance-compatibility`（一次开启三组兼容选项）
公式被当正文翻乱了	公式字体没被识别	用`--formular-font-pattern`指定公式字体模式
扫描件译文下有原文重影	原文没被盖住	加`--ocr-workaround`或`--auto-enable-ocr-workaround`
术语翻得不稳定	没给术语约束	用`--glossary-files`挂术语表