企业官网建设流程全解析

5分钟拿到双语PDF：BabelDOC让PDF翻译不跑版

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

你刚把一份 80 页的英文手册交给某款翻译工具，结果打开成品：页眉页脚挤成一团，公式变成了图片，"API"在第 3 页叫接口、第 21 页又叫应用程序编程接口。这种"翻完不能用"的产物，BabelDOC 这个开源文档翻译工具想解决的正是它——把 PDF 当成版式工程而不是纯文本，做到保留版式的 PDF 翻译，一次输出中英双语对照 PDF。

左列译文、右列原文，页码、栏位与公式位置一一对应

翻完为什么还是不能用

多数翻译软件把 PDF 当成一坨文字，于是三件事几乎必然发生：

• 版式塌掉：字号被放大、段落被撑出页边，标题和图注各跑各的。
• 公式变乱码：数学表达式被拆散成残字，或者干脆变成不可编辑的截图。
• 术语对不上：同一个名词翻出两三种叫法，审稿人一眼就能挑出来。

BabelDOC 的思路是反向的：先读懂 PDF 的版面结构（哪里是标题、哪里是正文、哪块是公式），翻译只替换文字内容，再把译文排回原来的位置。所以输出的 PDF 里，公式仍可编辑、版式和原文页对页。

从解析到输出，它干了什么

整个流程是一条三段流水线：

1. 结构解析：逐页拆出文本块、字体、字号、颜色与位置坐标，公式区域单独标记。
2. AI 翻译：按段落调用你指定的翻译服务，缓存机制让重跑不重复花钱。
3. 版式重建：用中文字体把译文重新排版进原文档框架，生成带水印的对照版和纯译文版两份 PDF。

这套流程的代码主体在 babeldoc/format/pdf/，其中 IL 中间层的实现文档见 docs/ImplementationDetails/，想深挖可以看。

五分钟出第一份双语 PDF

假设你还没装过 uv（一个很快的 Python 包管理器），先装它，再用它把 BabelDOC 装进独立的 tool 环境，不污染你的项目依赖：

curl -LsSf https://astral.sh/uv/install.sh | sh uv tool install --python 3.12 BabelDOC

然后配好翻译服务，跑一条最简命令。以 OpenAI 兼容接口为例，--pages 1-2表示只试翻前两页：

babeldoc --openai --openai-model "gpt-4o-mini" \ --openai-base-url "https://api.openai.com/v1" \ --openai-api-key "YOUR_API_KEY" \ --files "paper.pdf" --pages 1-2 --lang-out zh

参数就 6 个，其余上百个选项不用背，babeldoc --help里全都有。默认会同时输出双语对照版和纯译文版；如果想控制水印，加一个--watermark-output-mode即可，取值三选一：

--watermark-output-mode both # 带水印和去水印版本各一份

翻得更好一点的小习惯

• 先试 2 页再跑全篇：就是上面命令里的--pages 1-2，确认版式没跑再翻 80 页。
• 术语表：CSV 三列——源词、译词、目标语言，比如Machine Learning,机器学习,zh-CN。用--glossary-files terms.csv传入，全文译法自动统一；不传时它也会自动抽取高频术语。
• 100 页以上的大文档：加--max-pages-per-part 30按页数分块处理，降低内存压力；并发太高导致 API 限流就调低--qps。
• 扫描版 PDF：文本是图片时加--ocr-workaround，让它走 OCR 兼容路径。

支持多语言对与多种输出模式的命令行翻译器

幕后：三层流水线各一句话

• 解析层：babeldoc/pdfminer/ 负责把 PDF 的字节流读成对象树，babeldoc/docvision/里的版面模型判断每块内容的类型。
• 翻译层：babeldoc/translator/ 封装各家 AI 服务，段落级调用加结果缓存。
• 重建层：babeldoc/format/pdf/的 PDF 生成器按解析出的坐标与字体把译文写回，水印、页眉、图注位置不动。

想知道论文公式是怎么被识别又怎么还回去的，读 docs/ImplementationDetails/StylesAndFormulas/StylesAndFormulas.md 比看代码快。

收尾：它适合你吗

BabelDOC 的定位很直白：保留版式、保留公式、一次产出双语对照的开源 PDF 翻译工具，适合论文翻译、技术手册本地化这两类场景。现在就可以uv tool install --python 3.12 BabelDOC装上，拿手里任何一份英文 PDF 翻两页试试；更多参数与 Python API 用法，翻一翻仓库根目录的 README 和 docs 目录即可。

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