BabelDOC PDF翻译实操指南：三条命令产出排版不乱的双语PDF

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

你把一篇英文论文拖进某个翻译网站，拿到手的 PDF 里两栏结构散了、参考文献糊成一大坨。BabelDOC 是一款开源的 PDF 翻译工具：它把原页面的字体、位置、栏位当成固定网格，只替换文字本身，最终输出原文与译文并排的双语 PDF，公式、图表、多栏各就各位。

最小流程：三步跑通 PDF 翻译

这一节的目标只有一个：先让你看到结果，装、翻、验，各占一步。

第一步，安装。用 uv（比 pip 更快的 Python 包管理工具）装成命令行工具：

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

这步在干嘛：把 BabelDOC 连同依赖装进一个独立的 uv 工具环境，装完系统里多出一个babeldoc命令，用--help确认安装成功。

第二步，翻第一个文件，指定任意 OpenAI 兼容的 LLM 端点：

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

这步在干嘛：告诉它翻哪个 PDF、用哪个翻译模型。语言方向默认就是英译中（--lang-in默认 en、--lang-out默认 zh），不写方向参数也能跑。

第三步（可选），先试翻几页看效果：

babeldoc --files example.pdf -p "1,3,5-10" -o ./out

（openai 参数同上，此处从略）

这步在干嘛：只翻第 1、3、5~10 页，结果落到./out目录，确认排版能接受再全量跑。

跑完会在输出目录多出两份 PDF：example.zh.mono.pdf（仅译文）和example.zh.dual.pdf（双语并排对照），默认都带水印。效果大致是这样，左右两栏、图注、公式位置都跟原稿对得上：

为什么排版不乱

同样是调 LLM，凭什么它翻完不挤歪？把它想象成老印刷坊的雕版：版上的字槽（坐标、字体、栏位）雕好之后一次不动，印刷时只换刻进去的字，版子本身从不重刻。BabelDOC 的"字槽"是一份带结构信息的中间语言（Intermediate Language），整个流程分四步：

1. 解析：把 PDF 逐字拆开，记录每个字的位置、字体、大小、颜色，以及它属于哪个版面区域（正文、图、表、公式），存进结构化数据；
2. 识别：版面检测分出哪些块是正文段落、哪些是公式，公式和图直接跳过；
3. 翻译：只把段落文本连同样式信息发给 LLM，译文按原字号和颜色排回原位置；
4. 重渲染：从中间表示直接生成新 PDF，同时产出单语版和双语对照版。

所以"换字不换版"不是口号，是流程上就没给排版留改动的口子。实现代码在 babeldoc/format/pdf/document_il/，逐阶段的解析、段落识别、翻译、排版说明见 docs/ImplementationDetails/。

什么活儿它接得住

这一节帮你省 token：先分清哪些场景该用它，哪个场景别硬上。

适合的场景：

• 限时读英文论文：双语并排输出让你先扫译文、再回原文对图对公式，双栏结构和公式位置与原稿一致；
• 长文档里专业词多：术语表命中词条后，模型会收到"必须按表翻译"的指令，全文同一术语只有一种译法；
• 几百页的大文档：自动按页切块逐块翻译，再合并回一份完整 PDF，不用你手动切片。

不推荐的场景：非白底、非黑字的扫描版 PDF 别直接上——它的--ocr-workaround兜底只假设纯白背景黑字，彩色底、手写体这类扫描件走别的 OCR 管线更稳。另外两个已知限制心里有数就行：表格里的文字默认不翻译（--translate-table-text是实验开关，默认关）；作者与参考文献段落翻译后可能被合并成一段（官方已知问题）。

进阶调优：三个条件开关

这一节只展开最值钱的三项配置，其余参数babeldoc --help里都有。⚙️

如果你想让领域术语全文译法统一，就加--glossary-files glossary.csv。CSV 三列：source（原词）、target（译文）、tgt_lng（可选，如zh-CN），格式见 docs/example/demo_glossary.csv。段落命中词条时，命中的词表连同"按表翻译"的指令一起进提示词。系统默认还会自动抽取文档高频术语，用--no-auto-extract-glossary可关。

如果你跑几百页的大文档怕内存爆，就加--max-pages-per-part 50：自动切成每块最多 50 页逐块翻译，翻完自动合并回一份 PDF，效果和整篇跑一致。

如果你手上是白底黑字的扫描件，就加--ocr-workaround：它在原文位置垫一块白色矩形盖住原字、译文强制纯黑，视觉上等于重印了一页；不确定扫描页占比时用--auto-enable-ocr-workaround，检测到大量扫描页后自动启用。

顺带一提：参数太多的时候，把配置写进 TOML 文件，用--config config.toml加载即可，README 里有完整模板。

常见报错自查

这一节按"现象 → 原因 → 解法"列了最容易卡住人的五种情况，解法都能直接复制。

1. 双语 PDF 在某些阅读器里版面是碎的。原因：部分阅读器对翻译后的复杂内容流解析能力不足。 解法：加--enhance-compatibility，它一次性打开三个兼容增强开关（跳过 PDF 清理、译文页在前、禁用富文本翻译），先试这个再逐个排查。

2.--openai-base-url填了私有端点却报连接或格式错误。原因：工具只兼容 OpenAI 协议的 API，非 OpenAI 协议的服务接不上。 解法：走 OpenAI 兼容协议的中转（如 litellm），或换支持该协议的模型；本地模型（如 Ollama）的 API key 随便填个值就行。

3. 改了提示词，译文却跟上次一模一样。原因：相同文本会命中本地翻译缓存，直接复用旧结果，提示词根本没生效。 解法：加--ignore-cache强制重新翻译。

4. 输出 PDF 带"BabelDOC"水印，想要干净版。原因：--watermark-output-mode默认是watermarked。 解法：--watermark-output-mode no_watermark；想两份都要就用both。

5. 翻得很慢，怀疑卡死。原因：--qps（每秒请求数）默认只有 4，大文档是被限着速跑。 解法：--qps 10 --pool-max-workers 8，把并发提到匹配你 API 配额的数值；确认进度输出看--report-interval（默认 0.1 秒就该有动静）。

资源与下一步

• 官方文档：docs/（mkdocs 驱动，含支持语言列表）
• 各阶段实现细节：docs/ImplementationDetails/
• 翻译示例配置：examples/
• 术语表样例：docs/example/demo_glossary.csv

下一步建议：拿一篇你读过的英文双栏论文，跑一次不带任何进阶参数的默认翻译（只填--files和 openai 四件套），用输出效果给自己定个"这工具行不行"的基准；基准过了，再上术语表和--max-pages-per-part处理你的长文档。

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