企业官网建设流程全解析

BabelDOC PDF翻译实战：5分钟拿到第一份双语对照PDF

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

BabelDOC PDF翻译指的是用这个开源命令行工具，把一份英文 PDF 变成中英双语对照的 PDF：公式、表格和原版式尽量保留，译文按原文的版式重新排版，而不是简单覆盖在原文上。它用 Python 编写，要求 Python 3.10～3.13（官方示例用 3.12），翻译服务走任何 OpenAI 兼容接口（官方 API、DeepSeek、GLM、本地 Ollama 都行）。需要说明的一点：官方把这条 CLI 定位得更偏向"开发调试用"，普通用户也可以用，但大规模生产建议配套它的 WebUI 项目使用。

5分钟跑通第一个翻译任务

先安装。官方推荐用 uv 从 PyPI 装，装完得到一个独立的babeldoc命令：

uv tool install --python 3.12 BabelDOC babeldoc --version # 当前版本 0.6.2

没有 uv 的话，pip install BabelDOC也一样，它发布在 PyPI 上。装好之后，第一条翻译命令只需要四个关键参数：

babeldoc --openai \ --openai-model "gpt-4o-mini" \ --openai-base-url "https://api.openai.com/v1" \ --openai-api-key "sk-xxx" \ --files example.pdf -o ./out

• --openai是必选的开关，CLI 目前只接 OpenAI 协议，所以换服务只改--openai-base-url、--openai-model、--openai-api-key三个值即可，本地 Ollama 的 key 随便填一个非空字符串。
• -o指定输出目录，不写就输出到输入文件同目录。
• 默认会生成两份 PDF：单语译文版和双语对照版（默认左右并排），不想要哪份就用--no-mono或--no-dual。
• 第一次运行会下载布局分析模型和字体等资产，网络慢的话可以先跑babeldoc --warmup预下载并校验一遍。

BabelDOC 是怎么把 PDF 变成双语文档的

拿到结果之后再回头看流程会简单很多。整个管线在 docs/ImplementationDetails/README.md 里有逐步文档，源码集中在 babeldoc/format/pdf/document_il/（frontend 解析、midend 处理、backend 生成 PDF），核心环节是：

1. 解析：用 pdfminer/PyMuPDF 提取文本块、字体、坐标，生成一份内部 XML 中间表示（IL），而不是在原始 PDF 上动刀；
2. 布局识别：本地 ONNX 模型（doclayout.py）把每页划分成语段、公式、图片、表格区域；
3. 段落与公式：把离散文本块拼回段落，识别公式并做占位符保护，翻译时不会碰公式本身；
4. 翻译：调用 LLM，带本地缓存（重复文本不重复计费），术语表在这一步注入 prompt；
5. 重排与输出：匹配原字体风格、自动缩放字号，重新生成一份新的 PDF。

因为输出是新构建的 PDF，所以"译文塞不进原文框"这类问题靠缩放和重排解决，而不是叠加透明图层。

调优翻译质量：术语表、提示词与速率参数

语言方向默认-li en→-lo zh，其他语言对官方明确说只做了基础支持（比如英文作目标语言时减少词内换行），论文场景就用默认即可。

真正影响质量的是术语。它默认开启自动术语抽取：先让 LLM 扫一遍文档、挑出领域词，翻译时强制使用；不想用就加--no-auto-extract-glossary，想留档就加--save-auto-extracted-glossary，会在输出目录多生成一份 CSV 供下次复用。

手动术语表是 CSV，列为source,target,tgt_lng，tgt_lng可省略（仓库里有个示例 docs/example/demo_glossary.csv）：

source,target,tgt_lng AutoML,自动ML,zh-CN

用--glossary-files a.csv,b.csv传入多个文件（逗号分隔）。有个细节值得知道：术语表的名字取自文件名，翻译时只有命中当前文本片段的术语表才会进 prompt，所以文件名写清楚用途比堆一张大表更有效。

其余常用参数：

• --custom-system-prompt：自定义系统提示词，官方建议的典型用途是给 Qwen 3 注入/no_think指令；
• --qps（默认 4）：翻译接口限速，--pool-max-workers不填时直接取 qps 的值作为线程数；
• --min-text-length（默认 5）：短于这个长度的片段不翻译，避免"图1"这类碎词被翻坏；
• --formular-font-pattern/--formular-char-pattern：文档里公式字体比较特殊时，用字体名或字符特征显式标记公式，减少误翻。

扫描版 PDF 的处理方法

扫描 PDF 的判断和应对是三个独立开关：

• 默认会做一次"是否扫描件"检测，确认自己的文档是电子版时，加--skip-scanned-detection直接跳过，省时间；
• --ocr-workaround：在译文下方垫白色色块盖住原页文字，并强制全部文本为黑色，让双语版更干净。前提是白底黑字的清晰扫描件，彩色或复杂背景文档别用；
• --auto-enable-ocr-workaround：检测到超过 80% 页面是扫描页时自动启用上面那套 OCR 模式，适合"不确定混不混合"的批次任务。注意它与另外两个开关有交互关系，开启后初始检测阶段的手动设置会被覆盖。

需要提醒：它做的是"垫白底盖原文"的排版补偿，不会把图片里的文字重新识别出来，真正的 OCR 提取不在这条 CLI 的职责范围内。

大文件与批量：分段、并发与离线部署

几百页的文档直接翻，容易卡在中途或撑爆内存。做法：

babeldoc --files big.pdf --max-pages-per-part 50 \ --pool-max-workers 8 --openai --openai-model gpt-4o-mini \ --openai-base-url https://api.openai.com/v1 --openai-api-key sk-xxx

--max-pages-per-part 50会把文档切成每段 50 页分别翻译、再自动拼回完整 PDF；扫描检测默认只在第一段做。批量则直接多次--files：

babeldoc --files a.pdf --files b.pdf -o ./out

参数多到命令行难读时，改用--config指向一个 TOML 文件，命令行仍可覆盖单个值：

[babeldoc] openai = true openai-model = "gpt-4o-mini" qps = 10 output = "./out" max-pages-per-part = 50

完全断网的机器用离线资产包：联网机器上babeldoc --generate-offline-assets ./assets-dir生成一个 zip（模型+字体，文件名里带内容哈希，不能改名），目标机器上babeldoc --restore-offline-assets ./assets-dir恢复，传目录也可以，它会自动找对文件。

排错：兼容性、水印、页码范围与调试

• 某些阅读器里译文版式错乱：先加--enhance-compatibility，它等价于--skip-clean --dual-translate-first --disable-rich-text-translate的组合拳。代价是--skip-clean会让输出文件变大。
• 双语版想要上下交替：默认是左右并排，加--use-alternating-pages-dual改成原文页/译文页交替排布；--dual-translate-first则把译文页放前面。
• 水印：默认译文带水印，--watermark-output-mode no_watermark去掉，both则两个版本都输出。
• 只翻几页：--pages "1,2,1-,-3,3-5"支持区间与正负偏移写法，配合--only-include-translated-page让输出只含译了的那几页。
• 复现问题：--debug会把详细中间结果导出到~/.cache/babeldoc/working，排查"哪一段被识别错了"基本靠它；翻译结果默认走缓存，换模型或改 prompt 后记得加--ignore-cache强制重翻。

已知边界也要提前有数：作者和参考文献区翻译后可能合并成一段；横线、首字下沉暂不支持；超大页面会被跳过；表格内文字翻译是实验特性，需要--translate-table-text显式打开。

想深入某个环节（解析、段落切分、排版算法），按 docs/ImplementationDetails/README.md 里的顺序读对应文档即可，每个阶段都配了独立说明。

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