BabelDOC：把PDF论文翻译成中文还能保留公式、表格与排版，从安装到出双语文档只要几步
【免费下载链接】BabelDOCYet Another Document Translator项目地址: https://gitcode.com/GitHub_Trending/ba/BabelDOC
当你要把一份英文PDF论文翻成中文，并且要求译文里的公式、表格和版式不塌、不错位、不缺行时，可以直接用 BabelDOC：它先把PDF解析成中间表示，再对中间层文本做翻译，最后重新排版渲染成新文档。跑完一次翻译，你会得到一份单语PDF和一份原文/译文并排的双语对照PDF，可以直接打开核对哪一段的排版出了问题。
项目定位：翻译中间表示，而不是在原PDF上贴字
BabelDOC 的产出是"翻译后仍然能排版"的PDF，这是它与常见的"原页面上叠一层译文"做法的关键差异：
- 格式保留靠中间层：布局、字体、字号、颜色、公式占位都在中间表示里记录，翻译只替换文本，重新排版时按原样式落位（docs/ImplementationDetails/ 里有各阶段的实现说明）。
- 双语文档默认输出：每次翻译同时产出双语对照PDF和单语PDF，核对与交付两用。
- 翻译走 OpenAI 兼容 LLM：只支持 OpenAI 兼容接口（含本地模型），带翻译缓存和 QPS 限速；语言覆盖见 docs/supported_languages.md，项目当前主要面向英译中场景。
五分钟跑通第一个任务：安装、翻译、拿到双语PDF
先装好命令行，然后用一个 OpenAI 兼容的接口翻译一个PDF，最小命令如下：
uv tool install --python 3.12 BabelDOC export OPENAI_API_KEY="你的key" babeldoc --openai --openai-api-key "$OPENAI_API_KEY" \ --files paper.pdf--openai-model（默认 gpt-4o-mini）、--openai-base-url用来切换模型与端点，本地 Ollama 之类的服务 API key 随便填一个非空值即可；--lang-in/--lang-out默认就是 en → zh。跑完会在当前目录（或--output指定的目录）得到带水印的单语PDF和双语对照PDF，终端会打印两条输出路径，token 用量也会一并给出。
典型问题怎么解
按一次翻译任务的实际推进顺序看四个场景。
第一次翻译：从文件到输出路径
跑通的关键只有三点：给对文件、给对接口、找对输出。文件路径建议用绝对路径；多文件用多个--files传入，会依次处理。输出目录默认与输入同目录，想集中管理就加--output。第一次运行时它还会下载并校验模型与字体等资产，想提前拉好可以单独执行babeldoc --warmup只做资产预热。
术语一致性：从自动提取到术语库接管
专业词汇的译法由两层机制控制。第一层是自动术语提取：翻译前先从文档里抽取术语喂给提示词，可以用--save-auto-extracted-glossary把结果存成CSV，也可以--no-auto-extract-glossary关掉。第二层是你自己的术语库：CSV 三列source、target、可选tgt_lng，用--glossary-files指定：
source,target,tgt_lng AutoML,自动机器学习,zh-CN命中术语时，对应词表会被注入该段文本的提示词并要求模型遵循，同一术语在全文档内因此保持一致。
扫描版和超长大文档：先分段，再决定要不要OCR
已知不是扫描件时加--skip-scanned-detection，省掉检测耗时。确认是扫描件就用--ocr-workaround，前提假设是白底黑字——它会在译文下方垫白色块盖住原文、并强制文字为黑色；不想自己判断就改用--auto-enable-ocr-workaround，检测到高比例扫描页时自动启用。超过百页的文档用--max-pages-per-part指定每段页数，它会自动分段翻译、再合并回一份完整PDF。想先试水几页用--pages "1,2,1-"这类页码语法即可。
集成进流程：TOML配置与兼容性开关
批量跑或嵌进流水线时，把参数写进 TOML 配置文件，用--config指过去，README 里有一份可直接抄的示例配置。如果某些PDF阅读器打开输出有问题，加--enhance-compatibility，它等价于--skip-clean、--dual-translate-first、--disable-rich-text-translate三个开关的组合（代价是文件体积更大）。
提效技巧
- 吞吐调节用
--qps和--pool-max-workers组合：--qps限制请求速率（默认4），--pool-max-workers直接设定内部工作线程数（默认等于QPS），接口限流严就降、机器富余就升。 - 重复试错不花钱：翻译结果有缓存，改模型提示词之外的参数重跑时相同文本直接命中缓存；确需全部重翻才加
--ignore-cache。 - 离线或多机部署：在有网机器上
babeldoc --generate-offline-assets /path/to/dir打一个资产包，目标机上--restore-offline-assets恢复，包含全部字体和模型，结果一致。
项目内部结构
| 目录 | 职责 |
|---|---|
| babeldoc/format/pdf/ | CLI入口、高层翻译流程，以及内嵌的PDF解析器 |
| babeldoc/format/pdf/document_il/ | 中间表示的前端解析、中端处理、后端PDF生成 |
| babeldoc/docvision/ | 文档布局视觉模型（本地ONNX或RPC服务） |
| babeldoc/translator/ | LLM翻译调用与缓存 |
| docs/ImplementationDetails/ | 解析、段落、排版、PDF生成各阶段实现文档 |
处理顺序固定为：解析PDF建中间层 → 布局分析 → 段落识别 → 样式与公式 → 术语提取 → 翻译 → 排版 → 字体映射 → 生成PDF，每个阶段的权重占比在 babeldoc/format/pdf/high_level.py 的TRANSLATE_STAGES里能直接看到。
常见疑问
--pages的取值语法有哪些边界？支持逗号分隔的单页、区间与开边界，如"1,2,1-,3-5"：-表示到末页，3-5表示3到5页；不设置则翻译全部页码。
术语库CSV里的tgt_lng不填会怎样？可选项。填了的话，该条目只在归一化后与--lang-out匹配时才生效（大小写折叠、连字符转下划线）；不填则对所有目标语言生效。文件不存在或没有有效列时，会在日志里报错并跳过该文件，不会中断翻译。
输出PDF的水印怎么关？默认输出带水印版本。用--watermark-output-mode控制：no_watermark只出不带水印的，both同时出两种；旧的--no-watermark已标记弃用，不建议再用。
BabelDOC 的定位是把PDF翻译做稳：中间表示负责格式保真，LLM负责译文，双语文档负责核对。项目以 AGPL-3.0 发布，当前主要打磨英译中方向，其他语言组合建议先跑小样本验证。遇到可复现的解析或排版问题，把PDF样本直接提到仓库的 issue 里最有价值；涉及解析、翻译行为改动的贡献，按仓库要求先开 issue 讨论再提PR。
【免费下载链接】BabelDOCYet Another Document Translator项目地址: https://gitcode.com/GitHub_Trending/ba/BabelDOC
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
