企业官网建设流程全解析

BabelDOC PDF 双语翻译实操指南：三步拿到保留版式的双语 PDF

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

BabelDOC 是一个 PDF 文档翻译工具：把论文或报告交给它，它会翻译每一页的文本，然后生成一份双语对照 PDF（原文与译文并排）和一份纯译文 PDF。公式、表格、插图都留在原来的位置，不需要你手动搬运到 Word 里。装好命令行工具，跑一条命令就能出结果。

它到底能做什么：一份原文 PDF，换回两份译文 PDF

答案很简单：默认情况下，BabelDOC 一次跑完会给你两份 PDF。

第一份是双语对照版，同一页内原文和译文并排放置，适合边看边对照。第二份是单语译文版，只保留翻译后的内容。不想要的版本用--no-dual或--no-mono关掉其中一个即可。

对科研读者来说，最关键的是公式处理：BabelDOC 在解析阶段会识别出公式区域，翻译时把公式当作整体跳过，所以E=mc²这类内容不会被翻译成乱码，表格和图像的位置也不会漂移。

需要提醒的是，项目 README 里列了几条已知问题：作者和参考文献区域可能合并成一段、不支持首字下沉、特别大的页面会被跳过。用之前心里有数，遇到这些情况不用怀疑是自己操作错了。

用 uv 三步装好 BabelDOC 并完成首次翻译

第一步：安装并验证

官方推荐用 uv 安装，工具环境和你的日常环境互相隔离：

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

--help能正常打印参数列表，就说明装好了。也可以不走 PyPI：克隆仓库https://gitcode.com/GitHub_Trending/ba/BabelDOC后，在项目目录里用uv run babeldoc运行。

第二步和第三步：接上翻译服务，跑一条命令

BabelDOC 目前只接OpenAI 兼容的 LLM 接口。官方 OpenAI、第三方中转网关、本地的 Ollama 都行，区别只在 base-url 和 key 怎么填（本地模型随便填个占位值也能跑）。

babeldoc --openai --openai-model "gpt-4o-mini" \ --openai-base-url "https://api.openai.com/v1" \ --openai-api-key "your-api-key-here" \ --files paper.pdf

跑完后，输出目录里会多出两份 PDF，长这样：

多个文件就重复传--files；--output（或-o）可以指定输出目录，不指定就落在当前目录。

语言和输出参数速查：控制双语 PDF 的长相

这一节回答"我怎么控制输出"：常用的都是命令行参数，一张表列清楚。

关于语言范围要泼一点冷水：官方语言表列了一百多种语言代码，但 README 明确说当前主要打磨的是英文到中文，其他方向"能用但未充分测试"。完整清单看 支持的语言列表。

大 PDF 和扫描件的两个实战技巧

这一节解决两个高频麻烦：大文档翻译中途失败、扫描版 PDF 翻出来一坨字。

大文档：分页翻译和兼容性增强

• --max-pages-per-part 50：每 50 页切一段，逐段翻译后自动合并。一段失败不用整份重来。
• --enhance-compatibility：一键打开一组兼容性选项（等价于--skip-clean+--dual-translate-first+--disable-rich-text-translate）。某些 PDF 阅读器打开输出文件乱码时，先试这个；代价是--skip-clean会让文件体积变大。
• --qps（默认 4）和--pool-max-workers：控制请求速率和线程数。API 限流宽松就把 qps 调高，翻译会明显变快。
• 翻译缓存默认开启，重复段落直接复用结果；加--ignore-cache可强制重新翻译。
• 参数太多时，可以写成 TOML 配置文件，用--config 文件路径一次性传入。

扫描版 PDF：自动检测加 OCR 兜底

扫描件里是图片而不是文本，直接翻会得到空结果。BabelDOC 会自动检测文档是否以扫描页为主，确认自己手头不是扫描件时可以加--skip-scanned-detection省掉检测时间。

• --ocr-workaround：在译文下方垫白色色块盖住原文，并把译文强制为黑色。只适合白底黑字的文档。
• --auto-enable-ocr-workaround：检测到扫描占比很高时，自动启用上面的处理方式，不用你手动判断。

术语表与离线资产：把翻译调得更可控

这一节回答两个进阶问题：专业名词怎么固定译法？断网环境怎么跑？

用 CSV 术语表固定译法

传一个 CSV 给--glossary-files，文件包含三列：source（原文词条）、target（译文词条）、tgt_lng（可选，指定该条目生效的目标语言，如zh-CN）。比如一行AutoML,自动ML,zh-CN，翻译到中文时 "AutoML" 就会被固定译成"自动ML"。命中词条时，对应术语表会自动附进发给模型的提示词，要求译文遵守。

另外翻译前默认会先做一轮自动术语抽取，--no-auto-extract-glossary可以关掉；--save-auto-extracted-glossary能把抽取结果存成 CSV，方便你审阅后改造成正式术语表。

离线资产包：断网环境的一次性准备

模型和字体默认联网下载。断网部署时，先在有网的机器上生成离线资产包，再带到目标机器解压：

babeldoc --generate-offline-assets ./offline babeldoc --restore-offline-assets ./offline/offline_assets_*.zip

包内资产带 SHA3-256 校验，文件名里编码了清单哈希，所以不能改名；--restore-offline-assets也可以直接传目录，工具会自动找到正确的包。

想深入看解析、段落切分、翻译、排版各环节的实现细节，可以从 官方文档 和 翻译模块源码 入手。

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