BabelDOC 完整实战指南：保留原版式的 PDF 双语翻译

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

一条命令把英文论文喂进去，拿回一份原文与译文同页并排、版式基本不变的双语 PDF——这就是 BabelDOC：一个保留原排版的命令行 PDF 翻译工具，适合读英文文献的人、本地化技术文档的团队，以及做产品集成的开发者。

从一篇读不动的英文论文说起

想象一下：你要精读一篇三十页的英文论文。逐段复制去在线翻译，公式全变成乱码；交给"PDF 转 Word"的服务，回来的文档双栏变单栏，图表和参考文献的位置全乱了；直接把原文发给翻译模型，输出是一堆没有版式的纯文本。

想要的是：译文和原文一一对应，公式留在原处，参考文献还是参考文献。BabelDOC 的思路就是围绕这个来的——它不改动原文件，而是把译文并排渲染在原文旁边，输出一个可以直接归档、可以分享的双语对照 PDF。

项目定位：给 PDF 加一份"影子译文"

BabelDOC 本质上是一个命令行工具，同时也是被设计成可以嵌入其他程序的翻译引擎。它最有辨识度的做法是"双语对照"：默认情况下，译文和原文在同一页内左右并排，也可以切换成原文页、译文页交替排列。

它不是简单地把文字抠出来再塞回去。BabelDOC 先把 PDF 解析成一套中间结构——文字块、坐标、字体、样式、公式区域，翻译完成后再按这套结构重新排版。类似裁缝把西装拆开、照原样重新缝制，只换了内衬。

🚀 快速上手：两条命令跑通第一份双语 PDF

从安装到出结果，两条命令就够了。官方推荐用 uv 安装，项目要求 Python 3.10 到 3.13：

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

然后直接翻译。任何 OpenAI 兼容的接口都能用，包括本地 Ollama 部署的模型：

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

跑完后目录里会多出一个双语对照 PDF 和一个纯译文 PDF。有一句话值得先知道：README 明确说这个 CLI 主要面向调试，日常使用官方更推荐配套的在线服务，或者可自部署、接入更多翻译引擎的 PDFMathTranslate-next。

核心能力：对照排版、公式保持、术语一致

这三个能力决定了它和"通用翻译加重新排版"方案的差别，逐个说。

双语对照：并排、交替、单边都能选

默认模式下原文和译文在同一页内并排，译文紧跟原文，方便左右对照。加上--use-alternating-pages-dual后变成原文页、译文页交替排布，更接近纸质书逐页对照的体验；--dual-translate-first可以把译文页放到前面。只要单边结果的话，--no-dual或--no-mono分别关掉双语输出或单语输出。

版式与公式：先拆解，再重排

BabelDOC 的处理是一条流水线：解析 PDF、版面分析、段落识别、样式与公式处理、翻译、排版、字体映射，最后生成新 PDF，每一步的说明都在 中间层实现文档 里。

对公式的处理方式是"整块保留"：公式不参与翻译，只随段落整体搬运和重排。如果识别不准，可以用--formular-font-pattern或--formular-char-pattern告诉它哪些字体或字符属于公式。边界也要心里有数：README 的已知问题清单写明，线条暂不支持、首字下沉不支持、作者和参考文献区域翻译后可能被合并成同一段。

术语一致：自动抽词，也接受你的术语表

翻译前的术语抽取默认开启：系统先从文档里自动提取候选术语，保证同一术语全文译法一致。这步可以用--no-auto-extract-glossary关掉，也可以用--save-auto-extracted-glossary把结果存成文件。

手动控制走 CSV 术语表：文件要有 source、target 两列，可选 tgt_lng 指定目标语言，用--glossary-files传入，多个文件逗号分隔。文件名会作为术语表的名字出现在提示词里；翻译时只要某段文字命中了表内术语，对应的术语表就会连同"请遵守"的指令一起注入给模型。translator 模块 里就是这层翻译与缓存的实现。

🔧 进阶技巧：大文档、扫描件与离线环境

批量使用时主要会撞上四个麻烦，对应的开关都在 README 里。

大文档拆分。--max-pages-per-part 50会把文档按 50 页切段翻译，完成后自动合并回一份 PDF，避免长文档一次性塞进内存。

扫描件处理。--ocr-workaround专门处理白底黑字的扫描 PDF：在原文位置垫白色色块盖住原内容，译文统一强制为黑色。不想自己判断文档性质时，--auto-enable-ocr-workaround会在检测到超过约 80% 页面是扫描件时自动启用这套逻辑。

兼容性兜底。某些阅读器打不开输出文件时，--enhance-compatibility一把开启三组兼容选项（跳过清理、译文优先、关闭富文本翻译）。注意 README 的提醒：跳过清理会让文件体积变大。

离线部署。没有外网的机器，先在有网环境用--generate-offline-assets打包模型和字体，再到目标机器用--restore-offline-assets恢复，全程有 SHA3-256 校验，保证不同环境结果一致。

另外两件小事：常用参数可以写进 TOML 配置文件后用--config复用；翻译并发默认 QPS 为 4，可用--qps和--pool-max-workers调节。

典型场景

用得最多的有三类场景：学术阅读最直接，文档本地化最吃术语表，集成开发则是它的主业。

学术阅读是最对口的场景。英文论文进来，中英双语对照出去，双栏排版、图表标题、参考文献位置都尽量按原样保留，读文献时可以随时回看原文措辞。

技术文档本地化主要靠术语表发力。API 文档、产品手册这类文本对译名一致性要求高，把内部术语写成 CSV 传进去，再配合--min-text-length调低最短翻译长度（默认 5 个字符），短标签也不会被漏掉。

第三类是产品集成。BabelDOC 的主设计目标就是嵌入其他程序，CLI 只是调试入口；想要网页界面和更多翻译服务，官方给出的路径是自部署 PDFMathTranslate-next，Zotero 用户也有配套插件可用。

常见问题

下面五个问题基本是批量使用时最先撞上的，答案都来自 README 的口径。

只支持 OpenAI 吗？目前只接 OpenAI 兼容的 LLM 接口，本地模型（如 Ollama）也能跑，密钥随便填个占位值即可；传统翻译引擎（Bing、Google 一类）没有做优化，不建议用。

哪些语言对效果好？项目以英文译中文为主，2025 年 3 月才加入基础的英文目标语支持；官方支持语言列表覆盖了几十个语种，但依赖连字的语言（部分印度语系）暂不支持。

只想翻译部分页面？--pages支持 "1,2,3-5" 这样的写法，只翻指定页。

出了问题往哪查？加--debug，中间结果会导出到~/.cache/babeldoc/working，解析、排版各阶段的产物都能看。

表格和跨栏段落支持吗？表格翻译目前只是实验选项（--translate-table-text，默认关闭），跨页跨栏段落和大纲支持还在路线图里。

收束：适合谁，不适合谁

BabelDOC 适合三类人：每天读英文文献、想要双语对照的读者；需要把技术文档批量转成中文且术语统一的团队；想拿一条稳定 PDF 翻译流水线做集成的开发者。

它不适合：期望输出 Word 或 HTML 的人——目前只产 PDF；做连字语种翻译的人；以及指望 CLI 获得正式技术支持的用户，官方口径里 CLI 主要面向调试。定位务实，边界清楚，这类工具用起来反而安心。

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