BabelDOC PDF翻译实战指南：排版与公式原样保留，输出双语对照-平芜编程栈

BabelDOC PDF翻译实战指南：排版与公式原样保留，输出双语对照

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

把论文 PDF 翻译成中文，多数方案都有个通病：文字翻了，原排版被拆得稀碎，公式更是直接变成乱码，没法直接发给同行看。BabelDOC PDF翻译就是冲着这个问题来的——它先对原文档做版面分析（layout analysis），保住公式、图片和文本块的位置，再输出双语对照和单语两种结果。它能接任何 OpenAI 兼容的大模型，既能嵌进你的脚本里跑，也能在终端里一条命令直接出双语 PDF。

部署与上手

最短路径安装

从 PyPI 装，一条命令搞定。前提是你已经装好 uv 并配好PATH（官方安装方式可自行查阅）。下面这条命令用 uv 把 BabelDOC 装进独立的 3.12 环境，装完顺手验证一下命令行：

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

能打印出帮助列表，就说明环境就绪了。

源码方式

想改解析、排版逻辑，或者想看中间产物长什么样，直接从源码跑：

git clone https://gitcode.com/GitHub_Trending/ba/BabelDOC cd BabelDOC uv run babeldoc --help

uv 会自动处理依赖。之后把下文所有babeldoc换成uv run babeldoc即可。

按场景拆解核心用法

以下命令都以 OpenAI 兼容模型为翻译引擎，换模型名和接口地址就能切到别的服务。

整本 PDF 一次翻完

最常见的场景：一篇英文论文丢进去，拿到一份可以逐页对照原文的 bilingual 双语 PDF（同时还会产出一份单语版）。

下面这条命令指定模型和密钥，翻译整本paper.pdf，结果默认落在当前目录：

babeldoc --files paper.pdf --openai --openai-model "gpt-4o-mini" --openai-api-key your-api-key

关键参数就两个：--openai-model决定用哪个模型，--openai-api-key传密钥。如果你用的是自建网关或 Ollama 这类本地模型，再补一个--openai-base-url指向你的接口地址，本地模型的话密钥随便填个值都行。

只翻译指定页码

只想看摘要和结论，或者先抽几页试效果，没必要整本跑。

下面这条命令只翻译第 1、3、5 页，--pages的取值格式也支持"1-10"这种区间写法：

babeldoc --files paper.pdf --pages "1,3,5" --lang-in en --lang-out zh

--lang-in和--lang-out显式声明源语言和目标语言。这个项目目前主攻英语→中文，其他语言对基本没测过，用之前先有心理预期。

一次喂进多个 PDF

批量处理一堆文档时不用自己写循环：--files重复使用，把文件全部排进队列，工具会逐个处理。

下面这条命令把三个 PDF 一次性提交，共用同一套模型配置完成批量 PDF 翻译：

babeldoc --files doc1.pdf --files doc2.pdf --files doc3.pdf \ --openai --openai-model "gpt-4o-mini" --openai-api-key your-api-key

并行程度由--qps控制（默认 4），如果你的接口限速低，把它调小更稳。

术语保持一致

论文里专名多的话，模型很容易同一个词前后翻得不一样。解法是喂一个术语表：

命令里加--glossary-files demo.csv（多个文件用逗号分隔），CSV 文件需要source和target两列。工具会在翻译每个段落时自动查表，命中术语就把对应词条塞进提示词，要求模型照译。格式可参考仓库里的示例文件 docs/example/demo_glossary.csv。

进阶与边界

这些能力要么默认不生效，要么带着"先试再上"的适用条件：

⚠️表格文本翻译（实验性）：表格内的文字默认不翻译，加上--translate-table-text才会翻，排版仍可能出现异常，建议先在 20 页以内的文档上验证。

下面这条命令就是开启表格翻译的最小写法：

babeldoc --files table.pdf --translate-table-text \ --openai --openai-model "gpt-4o-mini" --openai-api-key your-api-key

大文档拆分翻译：加--max-pages-per-part 50，文档会被切成每 50 页一段分别翻译，再自动合并回去。上百页的文档建议直接开，省得一次失败从头再来。
兼容性兜底：输出在个别 PDF 阅读器里乱码或缺页时，先试--enhance-compatibility，它一次性开启跳过 PDF 清理、翻译页在前等一系列兼容选项。
扫描件处理：--ocr-workaround只适合白底黑字的文档——它会在译文下垫白色色块盖住原文并把文字强制置黑，背景复杂的文档别碰。