BabelDOC 上手指南：3 条命令翻译 PDF，公式、表格、排版全保留-平芜编程栈

BabelDOC 上手指南：3 条命令翻译 PDF，公式、表格、排版全保留

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

你手里有一份几十页的英文论文，想读中文版，可一丢给网页翻译，公式全变乱码、表格散架、排版面目全非。开源项目 BabelDOC 就是冲着这个痛点来的：它把 PDF 里的文字抽出来交给大模型翻译，再把译文按原始位置排回去，公式、表格原样保留，顺手还能生成一份中英双语对照版。

论文读不动？翻译一翻全乱

做研究、看技术文档的人都有过这种经历：想快速扫读一篇英文 PDF，翻译插件把文字翻了，但数学公式、坐标轴、表格结构全被打散，读起来比读英文还费劲。

BabelDOC 想解决的就是"既要翻得懂、又要保住排版"这件事。它不是把 PDF 拍平成纯文本再翻译，而是先保留文档结构，再把译文原位移回去，复杂公式也能照常阅读。

装好就能跑：安装与第一条翻译命令

一键安装

推荐用uv装，一条命令搞定（需要 Python 3.12）：

uv tool install --python 3.12 BabelDOC

装完跑一句babeldoc --help，能正常输出说明环境没问题。

首跑翻译

翻译单个 PDF，把模型和 key 填上即可：

babeldoc --openai --openai-model "gpt-4o-mini" --openai-api-key "你的key" --files example.pdf

要一次翻多个文件，把--files多写几次就行。默认会同时产出"双语对照版"和"纯译文版"两个 PDF，落在当前目录（可用--output指定到别处）。

它能帮你扛下哪几件事

公式和表格不丢：原位回填译文

普通翻译工具把 PDF 拍平成文本，结构和位置全丢。BabelDOC 是先做文档布局分析，认出哪些是正文、哪些是公式和表格，再把译文按原来的坐标填回去，所以翻出来的文档看着还是"同一份文件"，只是文字换了。这套排版逻辑可以在 docs/ImplementationDetails/Typesetting/Typesetting.md 里看到实现细节。

中英对照一眼看：双栏生成

它默认会生成一份左右分栏的双语 PDF，左栏原文、右栏译文，对照学习、逐句核对都方便。想只要双语版或只要纯译文版，用--no-dual/--no-mono控制输出哪种即可。

术语自己说了算：自定义术语表

专业文档里同一个词译法飘忽，读起来很出戏。BabelDOC 支持喂一份 CSV 术语表（列名source、target，可选tgt_lng），翻译时会优先照你的译法走。功能实现在 babeldoc/glossary.py，示例可参考 docs/example/demo_glossary.csv。

翻出来的 PDF 长这样

下面是一份带公式的英文论文，经 BabelDOC 翻译后的双语对照效果：左侧保留英文原文与公式图表，右侧是中文译文，公式、表格和排版基本原样保留。

想调得更顺手：几个常用进阶配置

大文档切块翻译

页数多的 PDF 容易超时或爆内存。加--max-pages-per-part 50，让它自动切成若干块翻译、再拼回完整文档，单块大小自己定。

扫描件 PDF 的 OCR 补救

扫描件本质是"图片里的字"，直接翻会漏内容。对"白底黑字"的扫描文档可以开--ocr-workaround，它会在译文下方垫白块盖住原文，并把文字统一转成黑字。注意：这招只对白底黑字有效。

换翻译引擎：OpenAI 兼容接口随便接

它只认 OpenAI 兼容接口，但"兼容"范围很宽：官方 API、各种中转、本地 Ollama 都能接，改--openai-base-url和--openai-api-key就行（本地模型 key 随便填个值也行）。翻译器逻辑在 babeldoc/translator/ 里。目前主要优化了英文到中文，其他语种对没做充分测试，可查 docs/supported_languages.md。

新手最容易踩的几个坑

接口只认 OpenAI 兼容：Bing、Google 这类传统翻译引擎没有针对性优化，别硬接，优先选 LLM 模型，如gpt-4o-mini、deepseek-chat、glm-4-flash。
语言对要认准：默认--lang-in en、--lang-out zh，其他组合可能翻得不稳，建议先拿英译中试水。
特殊 PDF 打不开：个别结构特殊的文档翻译后兼容性差，先加--enhance-compatibility（等价于跳过清洗、译文页前置、关闭富文本翻译）再试。
key 别忘填：--openai-api-key空着会直接报鉴权错误，这是新手最容易漏的参数。
路径尽量用绝对路径：传相对路径有时定位不到文件，建议给全路径。

它到底适合谁用

啃英文论文的学生 / 研究者：边对照边读，公式图表不丢，最对路。
读外文技术文档的工程师：术语表 + 双语对照，能快速过一遍资料。
想自托管、可离线部署的团队：提供离线资源包（--generate-offline-assets/--restore-offline-assets），内网环境也能跑。
不太适合：只想要"一句话纯文本翻译"的场景——它更偏文档级、重排版，纯文本需求用轻量工具更快。