三步把论文PDF译成双语版：BabelDOC新手完全指南

三步把论文PDF译成双语版：BabelDOC新手完全指南

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

英文论文里密密麻麻的公式和文字，是不是让你头疼？BabelDOC 是一个开源的 PDF 翻译工具：把原始 PDF 丢进去，它会还你一份纯译文 PDF 和一份原文对照的双语 PDF，排版尽量保持原样，公式、表格基本不被破坏。如果你经常要读英文论文或技术文档，它值得一试。

BabelDOC 到底能做什么

先说清楚它能干什么，再决定要不要上手。BabelDOC 负责的是 PDF 翻译里最麻烦的一环——"把文字换掉，但版式别乱"，内部要连续完成四步：

1. 解析：把 PDF 里的文字、字体、颜色、位置全部提出来；
2. 布局分析：用 ONNX 布局模型区分正文、公式、表格、图片；
3. 翻译：调用 LLM 逐块翻译，过程中还会自动提取高频术语；
4. 排版：根据译文长度动态调整字号，塞回原来的位置。

几个对实际使用很有帮助的特性：

• 默认输出两种文件：单语版（mono）和原文对照版（dual）；
• 公式和代码会被自动识别保护，不参与翻译；
• 术语表机制，可以把关键术语的译法固定下来；
• 支持只翻译指定页码，不用整本处理；
• 扫描版 PDF 有专门的兜底方案（OCR workaround）。

想读代码的话，可以从翻译入口 babeldoc/format/pdf/high_level.py 开始；每个阶段的原理，docs/ImplementationDetails/ 目录下都有对应文档。

三步跑通第一次 PDF 翻译

这一节只要三条命令，就能把翻译跑起来。

第一步：安装。需要 Python 3.10 到 3.13。官方推荐用 uv 安装，环境自动隔离：

uv tool install --python 3.12 BabelDOC

没有 uv 的话，pip install BabelDOC也可以。首次运行会自动下载模型和字体；想提前下完再断开网络，可以先跑一次babeldoc --warmup。

第二步：准备翻译服务。BabelDOC 走 OpenAI 兼容的 LLM API，自建的 Ollama 等本地模型也行，API key 随便填一个占位值。建议把 key 放进环境变量，别写进命令行。

第三步：执行翻译。

babeldoc --openai \ --openai-model "gpt-4o-mini" \ --openai-base-url "你的API地址" \ --openai-api-key "你的key" \ --files paper.pdf --output ./out

跑完在./out里能拿到两个文件：

• paper.zh.mono.pdf：纯中文译文版；
• paper.zh.dual.pdf：双语对照版，原文和中文并排。

下面是一次真实的翻译效果，一篇 EEG 论文被译成了中英双语：

默认是英译中，换语言对用--lang-in和--lang-out，支持的语言清单见 docs/supported_languages.md。

常用参数速查

跑通之后，你会想控制得更细。下面是出现频率最高的几个开关，不用背，用的时候查：

术语表怎么用

术语表就是一个两列的 CSV：source和target：

machine learning,机器学习 neural network,神经网络

翻译时，哪个文本块命中了表里的词，这些词就会自动带进提示词里，要求模型照着译。仓库里有一份现成示例：docs/example/demo_glossary.csv。另外 BabelDOC 翻译过程中会自动抽取高频术语，想把它存下来复用，加上--save-auto-extracted-glossary。

遇到不听话的 PDF，试试这四招

真实的论文往往比示例刁钻。卡住的时候按症状对号入座：

1. 扫描版，文字选不中。加--ocr-workaround：它会在原文下面垫白色色块、把译文强制涂黑，相当于在扫描版上"重新排版"。只适合白底黑字的文档。分不清是不是扫描版时，可以试--auto-enable-ocr-workaround让工具自己判断。反过来，确定不是扫描版就用--skip-scanned-detection跳过检测，速度更快。

2. 文件太大，内存吃紧。--max-pages-per-part 50会自动把文档切成每 50 页一段，逐段翻译再拼回去；再配合--pool-max-workers压低并发，就能救回快崩的机器。

3. 某些阅读器打开显示异常。不同 PDF 阅读器脾气不同，先丢一个--enhance-compatibility试试，它把几个兼容性增强选项打包打开。代价是文件体积变大。

4. 想看内部到底发生了什么。加--debug运行，中间结果会导出到~/.cache/babeldoc/working，布局、分词、排版每一步都能翻。排查版式问题还有--show-char-box，会在页面上画出字符边界框。

最后提醒几个已知限制（README.md 里列着）：作者列表和参考文献部分翻译后容易并成一段；超大的页面会被跳过；装饰性线条和首字下沉暂不支持。论文被影响时，你知道该找什么了。

从偶尔用到长期用

只是偶尔翻译，上面的命令就够。用得多，可以往这几个方向走：

参数存进配置文件。不想每次敲长命令，就写一个 TOML 文件，用--config加载：

[babeldoc] files = "./paper.pdf" output = "./out" lang-in = "en" lang-out = "zh" qps = 4 glossary-files = "./terms.csv" watermark-output-mode = "no_watermark"

批量翻译。--files可以写多次，一条命令处理多个文件；套一层 shell 循环，整个目录就能跑完。

离线环境。在能联网的机器上执行babeldoc --generate-offline-assets ./assets，生成包含全部模型和字体的资产包，再到目标机器上用--restore-offline-assets恢复即可。注意包名里编码了校验和，不能改名。

嵌入到自己的程序里。BabelDOC 的设计目标就是被嵌入：它提供 Python API（入口在high_level），可以在你自己的工具里直接调用整条翻译流水线；想要带 WebUI 的形态，可以看看官方文档推荐的自部署方案 PDFMathTranslate-next。

一句话收尾：BabelDOC 把"逐页翻译再手动排半天版"变成了"一条命令，两份 PDF"。先拿一篇短论文试出双语效果，再按需要调参数，就是上手它最快的方式。

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