企业官网建设流程全解析

BabelDOC：PDF 翻译工具完整指南，本地跑通开源 PDF 翻译

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

刚领到一篇 200 页的英文论文，你想逐页翻成中文，却不想让排版散架，也不想把文件传上云端。BabelDOC 就是干这件事的开源 PDF 翻译工具：它是一套本地运行的 Python 库加命令行，把英文 PDF 译成中文，公式和图表留在原位，默认产出原文与译文左右对照的双语 PDF。与网页翻译或云端服务不同，它的解析、排版、渲染全部跑在你自己的机器上，文件不出内网。

五分钟跑起来

环境要求：

• Python 3.10 及以上
• 一个 OpenAI 兼容接口的模型与 API Key（本地 Ollama 也可以）
• 推荐安装 uv 管理依赖

安装步骤：

1. git clone https://gitcode.com/GitHub_Trending/ba/BabelDOC
2. 进入目录执行uv tool install .，把babeldoc装进 PATH
3. 运行babeldoc --openai --openai-model "gpt-4o-mini" --openai-base-url "https://api.openai.com/v1" --openai-api-key "你的key" --files example.pdf

第一个成功标志：当前目录出现example.pdf_dual.pdf（双语对照）和example.pdf_mono.pdf（纯译文），公式、栏位、图片位置与原文一致，打开看一眼就知道对了。

--openai-base-url指向任何 OpenAI 兼容端点即可，本地部署 Ollama 时 API Key 随便填一个占位值。

它是怎么运转的

BabelDOC 内部是一条三层流水线：

• 解析层：解析 PDF 对象树，生成中间层（IL）。入口在babeldoc/format/pdf/high_level.py，解析器位于babeldoc/pdfminer/。
• 中间层：版面检测（babeldoc/doclayout/）划分图、表、文本区，babeldoc/format/pdf/document_il/midend/里的layout_parser.py、paragraph_finder.py、il_translator.py依次完成段落切分、公式占位符保护和调用翻译服务。
• 输出层：document_il/backend/pdf_creater.py基于 PyMuPDF 重排译文、映射字体，还原公式占位符，产出双语与单语两份 PDF。

术语可以锁定。准备一个逗号分隔的 CSV，配合--glossary-files传入：

source,target attention mechanism,注意力机制

翻译时命中词条的段落会带着这份术语表发给模型。不指定时，automatic_term_extractor.py会自动抽取术语，加--no-auto-extract-glossary可关闭。

三个场景，三种用法

场景：精读长篇论文。做法：1) 用--openai-model指定推理能力强的模型；2) 输出后直接读*_dual.pdf的左右对照版。效果：中英文在同一页左右对照，手机上也能逐段核对，公式不用二次处理。

场景：批量处理部门文档。做法：1) 一条命令重复--files传多个文件；2) 用--pages "1,5-8"只译需要的页；3) 相同段落命中babeldoc/translator/cache.py的缓存，不重复调 API。效果：多份报告的翻译跑一晚上就够了，token 花费按实际段落计。

场景：无外网的内网环境。做法：1) 在能联网的机器执行babeldoc --warmup预取模型与字体；2)--generate-offline-assets /path/dir打出离线资产包；3) 内网机器用--restore-offline-assets还原后直接翻译。效果：整条 PDF 翻译流水线零外网依赖，SHA3-256 校验保证各机器资产一致。

踩坑速查

• 现象：输出目录里只有单语 PDF。原因：命令带了--no-dual，只关掉了双语输出。修复：去掉该参数重跑；同理--no-mono会关掉单语版。
• 现象：公式被当正文翻译，译文乱码或排版错位。原因：字体特征不明显，公式没被识别为占位符。修复：加--formular-font-pattern或--formular-char-pattern，让styles_and_formulas.py按规则把公式整段保护起来。
• 现象：首次运行极慢甚至超时。原因：布局检测模型和字体在首次运行时才下载。修复：先执行babeldoc --warmup；离线环境直接用离线资产包还原。

从用到贡献

参与路径：1) 通读docs/ImplementationDetails/README.md，建立流水线全貌；2) 用--debug本地复现你遇到的问题，拿到中间产物；3) 提交带最小可复现 PDF 的 issue，或补一条文档修正；4) 涉及解析、渲染、翻译行为的大改动，先开 issue 讨论再提 PR。

适合的方向：bug 报告（附上最小可复现 PDF）、docs/下的文档修正、以及针对特定 PDF 结构的兼容性小修（代码在babeldoc/format/pdf/）。项目采用维护者主导模式，动手前看一眼docs/CONTRIBUTING.md的约定即可。

回到开头那篇 200 页的论文：BabelDOC 让翻译在本地完成，公式、栏位、图片一个不丢。打开终端，配好 API Key，敲下babeldoc --openai ... --files your_paper.pdf，几分钟后打开目录里那份双语对照 PDF 就行。

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