BabelDOC：排版不乱的 PDF 翻译，从零到双语对照只需 5 分钟

BabelDOC：排版不乱的 PDF 翻译，从零到双语对照只需 5 分钟

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

拿到一份英文学术 PDF，你多半不想要一堆翻译出来的纯文本，而是一份排版保留、中英对照的双语 PDF。BabelDOC（Yet Another Document Translator）干的就是这件事：解析 PDF 底层结构，把正文原位替换成译文，公式、表格、图片留在原处，一条命令行就能跑完整个翻译流程。

初识 BabelDOC：排版保留才是它的核心

大多数 PDF 翻译的思路是"抽文字 → 翻译 → 贴回去"，贴不回去的地方就是排版错乱的重灾区。BabelDOC 的路线不一样：先把 PDF 解析成一层中间结构（IL），识别出版面区域、段落边界和公式块，然后只把正文送给大模型，公式这类不可翻译的元素按原坐标重新渲染回新 PDF。

动手之前，有三件事值得知道：

• 翻译只走 OpenAI 兼容接口——官方 API、各家兼容网关、甚至 Ollama 本地模型都行，换个--openai-base-url和 key 就能切换
• 版面分析模型是本地 ONNX 推理（DocLayout-YOLO 系），不需要 GPU 云服务
• 术语抽取默认开启：文档先过一遍候选术语提取，之后同篇文档里同一词尽量保持一致

它内部的七个阶段（解析 → 版面 → 段落 → 样式与公式 → 翻译 → 排版 → 生成）都有文档：docs/ImplementationDetails/。

环境准备：5 分钟跑通第一次 PDF 翻译

安装与模型预热

uv tool install --python 3.12 BabelDOC babeldoc --warmup

--warmup会把布局和字体资产全部下载校验一遍，避免第一次正式翻译时卡在下载上。

✅ 第一次英译中翻译

babeldoc --openai \ --openai-model "gpt-4o-mini" \ --openai-base-url "https://api.openai.com/v1" \ --openai-api-key "your-api-key" \ --files example.pdf

源语言默认en、目标语言默认zh，所以最常见的英译中场景不用写--lang-in/--lang-out。跑起来后终端会显示各阶段的进度条，结束时打印 token 用量和缓存命中情况。

输出文件与翻译缓存

默认会产出两份文件：双语对照版（dual，原文与译文同页左右并列）和纯译文版（mono），用--no-dual或--no-mono可以只留一种。译文 PDF 默认带水印，--watermark-output-mode可切到no_watermark或both。

翻译结果缓存在~/.cache/babeldoc下的 SQLite 库里，按"引擎 + 参数 + 原文"唯一键存储：同参数重跑同一份文档时，已缓存的段落直接命中，不重复花钱；想强制重翻就加--ignore-cache。库会自动清理，只保留最近 5 万条记录，实现见 babeldoc/translator/cache.py。

按文档类型调参数

如果你只把 BabelDOC 当学术论文翻译工具用，默认参数往往就够用。下面是三类高频需求的对应开关。

🔧 让数学公式原样保留

公式字符是靠"公式字体 + 特殊 Unicode + 竖排文字 + 上下标标记"识别的，识别出的公式块不会进翻译队列，只按原偏移量渲染回去。如果你的论文用了特殊数学字体或自定义符号，可以补充识别规则：--formular-font-pattern指定公式字体名正则，--formular-char-pattern指定字符范围正则。

表格里也有文字？加--translate-table-text（实验特性），它会启用 RapidOCR 来处理表格内文本。

双语 PDF 的排布方式也可以选：

📄 扫描 PDF 怎么翻译

先保证扫描件质量：分辨率 300dpi 以上、文字方向正确，这是 OCR 类流程的通用底线。

• BabelDOC 会自动检测文档是否为扫描件（扫描页占比超过 80% 即判定为重度扫描）。加上--auto-enable-ocr-workaround，检测到重度扫描时会自动启用 OCR 处理，省去手动判断
• 明知是电子 PDF 时，加--skip-scanned-detection跳过检测，直接省掉这一步的时间
• --ocr-workaround（实验特性）假设白底黑字：会在译文下方垫白色色块盖住原文、并强制译文黑色，适合背景干净的扫描件
• 长文档建议配合--max-pages-per-part 50分块翻译，完成后自动合并

📚 系列文档术语怎么统一

手动术语表用--glossary-files terms.csv，CSV 三列：source、target、tgt_lng（最后一列可省略，省略即对所有目标语言生效），格式可参考 docs/example/demo_glossary.csv：

source,target,tgt_lng AutoML,自动ML,zh-CN

另外，自动术语抽取默认是开着的：它从文档里提取候选术语并约束后续翻译。加--save-auto-extracted-glossary可以把抽取结果导出成 CSV 放到输出目录，人工校对后就能作为下一批文档的术语表复用；不想要这个环节就--no-auto-extract-glossary关掉。

🐛 常见坑与排查

输出 PDF 在某些阅读器里打不开或错版

先试--enhance-compatibility，它等于一次打开--skip-clean+--dual-translate-first+--disable-rich-text-translate三个兼容选项。代价是文件体积会变大，但兼容性最好。

翻译太慢、中途失败、想省 token

• 大文件用--max-pages-per-part分块，每块失败不用从头再来
• 只想先试几页：--pages "1-5"指定页码，再配合--only-include-translated-page只输出翻译过的页
• 速度旋钮：--qps限请求速率（默认 4），--pool-max-workers直接设内部工作线程数
• 跑过一遍再跑同一份文档时留意结尾日志里的缓存命中 token 数，命中意味着那部分没有重复计费

💡 怀疑译文是旧缓存时，--ignore-cache强制全部重翻。

先了解这些已知限制再下结论

README 的 Known Issues 一节列得很直白：作者信息和参考文献区可能合并成一段；不支持横线；不支持首字下沉；超大页面会被跳过。另外项目主要优化的是英译中，其他语言对基本没测过（2025 年 3 月起加了基础的英译英支持）。遇到怪现象，先对照这份清单，能省不少排查时间。

延伸：配置文件、离线资产包与文档

命令行参数都能写进 TOML 配置文件，--config my.toml加载，长参数就不用每次敲了：

[babeldoc] openai = true openai-model = "gpt-4o-mini" lang-in = "en" lang-out = "zh" max-pages-per-part = 50 watermark-output-mode = "no_watermark"

无网环境可以用离线资产包：在有网机器上babeldoc --generate-offline-assets ./assets生成包含模型和字体的压缩包（文件名里编码了文件清单哈希），目标机器用--restore-offline-assets还原，两侧都有 SHA3-256 校验。

想深挖实现的话，docs/ 下的 ImplementationDetails 按七个阶段拆开讲了原理和配置项；中间表示（IL）的样例 XML 放在 examples/，对照着看解析阶段会清楚很多。要提醒一句：官方定位里这个 CLI 更偏调试入口，需要完整 WebUI 或更多翻译服务的话，可以去看自部署封装 PDFMathTranslate-next。

下一篇 PDF 挑一份带公式的英文论文，按"环境准备"一节把命令跑一遍，是最快的上手方式。输出不符合预期时，先读 docs/ImplementationDetails/ 定位问题出在解析、翻译还是排版阶段；能稳定复现的问题，欢迎带着 PDF 样本去项目 issue 区提交。

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