BabelDOC PDF翻译教程：3分钟拿到双语对照版，公式和排版不动

BabelDOC PDF翻译教程：3分钟拿到双语对照版，公式和排版不动

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

BabelDOC 是一个开源的 PDF 翻译工具，能把英文 PDF 直接翻成中英双语对照版，公式、表格、排版都留在原位，文档全程不离开你的电脑。装好之后，一条命令就能开始翻译论文。

核心能力速览：产出双语对照 PDF 的开源 PDF 翻译工具

BabelDOC 是一个用来翻译 PDF 文档的开源工具，翻译结果保留原始版面。几个判断点：

• 双语对照：默认输出"原文+译文"并排在同一页的双语 PDF，同时给你一份纯译文版本
• 公式不破坏：公式区域先被识别保护，只翻译文字部分，公式符号原样保留
• 多语言：支持 20 多种语言，当前重点打磨英文转中文，语言清单见支持语言列表
• 本地运行：程序在你机器上跑，翻译调用 OpenAI 兼容接口，也可以接自己部署的模型

🚀 快速开始：3 条命令跑通 BabelDOC

安装只需要一条命令，前提是装好了 uv 这类 Python 工具链：

uv tool install --python 3.12 BabelDOC

然后直接翻译一份 PDF，翻译走 OpenAI 兼容接口：

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

跑完之后，当前目录会多出一个同名 PDF：双语对照版和单语版各一份。想用哪个模型，改--openai-model和 base-url 就行。

真实用法：从读论文到术语一致的 3 个场景

读英文论文，边看中文边对原文

读译文顺，但想核对作者的原话时，要在两个 PDF 之间来回切。BabelDOC 生成的双语版把原文和译文排在同一页，视线不用离开。想反过来先看译文，加--dual-translate-first；只要单语版就加--no-dual。

babeldoc --dual-translate-first --files paper.pdf

你拿到的就是下面这种效果：左侧英文原文，右侧中文译文，公式区域两侧完全一致。

术语总被翻得不一致

同一个概念，模型可能这段译"机器学习"、下段译成"machine learning 学习"。BabelDOC 支持术语表：一个 CSV，三列source、target、tgt_lng。翻译时系统会把当前段落和术语表比对，命中了就把相关词条写进提示词，要求模型照译。

source,target,tgt_lng machine learning,机器学习,zh-CN neural network,神经网络,zh-CN

babeldoc --glossary-files terms.csv --files document.pdf

仓库里有一份术语表演示文件可以参考格式。翻译完成后，全文术语统一成你定的写法。

大文档翻译慢、中断要重来

几百页的文档一口气翻，耗时长，中途失败就前功尽弃。--max-pages-per-part把文档按页数切成块，逐块翻译，结束后自动合并：

babeldoc --max-pages-per-part 50 --files large_document.pdf

最终产出的仍然是一份完整的双语 PDF，中途某一块失败也不会连累整份文档。

进阶与技巧：4 个容易被忽略的参数

• --pages "1,2,1-,-3,3-5"：只翻译指定页码。想在整本书上先翻摘要和前两章看效果时，用它省 API 开销。
• --qps 10配合--pool-max-workers 8：默认 QPS 是 4，你的 API 额度宽裕时调高，大文档的翻译时间明显缩短。
• --custom-system-prompt "/no_think 你是一名专业、地道的机器翻译引擎。"：接 Qwen3 这类会输出思考过程的模型时加上，避免思考文本混进译文。
• --generate-offline-assets /path/to/dir：在联网机器上把模型和字体打成一个离线包，拷到内网机器再用--restore-offline-assets还原。部署到无外网环境时用得上。

原理速览：一页 PDF 怎么变成双语 PDF

整条流水线分两段：解析和渲染。先用 pdfminer 和 PyMuPDF 把页面解析成一份中间 XML 表示（document_il），再经过版面分析、段落识别、样式与公式处理，把文字交给 LLM 翻译，最后由排版引擎重排字体、拼出新的 PDF。核心思路是：只翻译"文字"，页面的"骨架"交给排版重建。每个阶段的细节在实现细节文档里按执行顺序写好了。

避坑与常见问题

只支持英文转中文吗

当前重点打磨英文转中文，另外加了基础的中文转英文。其他语言对在列表里，但组合没有被充分测试，效果自行验证。

译文在个别 PDF 阅读器里打开报警告或显示异常

加--enhance-compatibility重试，它等于一次性打开跳过清理、译文置前、关闭富文本翻译三个兼容选项。注意跳过清理会让文件体积变大。

扫描版 PDF 没有文字层，翻不了

用--auto-enable-ocr-workaround。检测到文档大面积是扫描图时，它会自动切到 OCR 路线：在译文下方垫白色色块盖住原文，文字强制纯黑。前提是白底黑字。

第一次运行特别慢

首次运行要下载模型和字体。可以先跑babeldoc --warmup预下载，或者用离线包的方式绕开。

能用自己部署的模型吗

只要是 OpenAI 兼容接口就行，Ollama 这类本地服务直接填 base-url，api-key 随便给个非空值。

想弄清某一页具体是怎么被拆开再拼回去的，按顺序读一遍docs/ImplementationDetails/ 比看代码快得多。遇到解析失败的 PDF，附上可复现的样张去提 Issue，是修得最快的路径。

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