企业官网建设流程全解析

BabelDOC 快速上手：一份命令把英文 PDF 变成双语对照译文

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

手里有一份英文论文 PDF，想快速看懂，或者要把外文资料交给团队时保留原文作对照？BabelDOC 就是干这件事的 PDF 翻译工具：它解析 PDF 排版，调用大模型翻译正文（公式、表格、参考文献这类结构也会处理），最后输出一份上下对照的双语 PDF——上面是原文，下面是对应译文，版式基本不动。

场景一：一条命令装好 BabelDOC

这一步会下载 BabelDOC 及其依赖，并注册babeldoc命令，之后在任何目录都能直接调用。推荐用 uv 安装，同时指定 Python 3.12 运行环境：

uv tool install --python 3.12 BabelDOC

装完跑一次babeldoc --help能列出全部参数。如果你要改代码、做二次开发，则从源码安装更合适：git clone https://gitcode.com/GitHub_Trending/ba/BabelDOC后进入目录，用uv run babeldoc --help直接跑仓库里的版本。

场景二：跑出第一份双语 PDF

这一步会完整翻译 example.pdf：先解析版式，再把英文段落逐段送进翻译服务，最后在原文下方排上译文。最简命令只需要三个参数——文件路径、源语言、目标语言（默认就是 en 到 zh，不写也可以）：

babeldoc --files example.pdf --lang-in en --lang-out zh

运行需要能访问翻译服务。BabelDOC 接的是 OpenAI 兼容接口，四个参数指定即可：--openai开启、--openai-model填模型名（如gpt-4o-mini）、--openai-base-url填接口地址、--openai-api-key填密钥。任何兼容该协议的模型服务都能接，不限于 OpenAI 官方。

翻译完成后，输出目录里会得到一份双语 PDF：原文和译文逐段对齐，方便边读边对照。

场景三：只翻译指定页面，或一次处理多个文件

论文有 80 页但你只关心前 5 页的正文？--pages参数控制翻译范围，语法支持单页、区间和省略写法，比如1,3,5（指定页）、3-5（区间）、1-（从第 1 页到结尾）、-3（前 3 页）：

babeldoc --files example.pdf --pages "1,3,5"

反过来，手头有好几份文档要一起翻，就把--files重复使用，每个文件写一次，其余参数共享：

babeldoc --files doc1.pdf --files doc2.pdf --files doc3.pdf

场景四：表格、公式和模型选择

前面几节覆盖了大多数情况，这一节讲几个按需才用的开关。

• 表格文字：默认不翻译表格内容。报告类文档表格多的话，可以加--translate-table-text打开。官方标注这是实验性功能，排版可能有瑕疵，建议先小范围试。
• 公式：正文里的数学公式会被识别并原样保留，不参与翻译，所以公式密集的论文可以放心整篇跑。
• 术语表：专业文档可以用--glossary-files挂一个 CSV 术语表（仓库里 docs/example/demo_glossary.csv 有示例格式），命中的术语会强制按表中译法输出。另外 BabelDOC 默认会自动抽取文档术语保持一致性，不需要时可以关掉。
• 模型怎么选：日常阅读用轻量模型（如gpt-4o-mini）速度和质量都够用；交付级文档换成更强的模型（如gpt-4）。同一套参数换模型名就行。
• 长文档：页数很多时可以用--max-pages-per-part把文档切块翻译，降低单次失败的影响范围。

更多参数的含义都写在babeldoc --help里，原理细节可以参考 docs/ImplementationDetails/ 下的解析、排版等文档。

避坑清单：这几个问题最常被踩

• 扫描件先确认能提取文字。BabelDOC 翻译的是 PDF 里的文本层；纯扫描图需要你先做 OCR，或至少跑一次小规模测试确认提取正常。
• API 四件套缺一不可。--openai标志、模型名、base-url、api-key 少一个都会直接报错，先把这四个配通再谈参数调优。
• 实验性开关先试后上。--translate-table-text、--ocr-workaround等标注 experimental 的参数，正式翻译前先在一两个文件上验证输出。
• 长文档留个工作目录。用--working-dir指定中间产物位置，失败重跑时能直接复用已翻译的缓存，不用从零开始。
• 翻译质量看术语而非全文。先翻一两页，重点核对专业术语是否一致，再决定要不要上术语表，比整篇翻完再返工省事得多。

下一步

把最常用的组合存成 shell 历史或写成小脚本，下次打开终端就能直接翻。装好之后，拿你手上任意一份英文 PDF 跑一遍场景二的命令，看第一份双语对照输出，比读十篇教程都直观。

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