企业官网建设流程全解析

BabelDOC PDF 翻译教程：保留公式与版式，生成中英对照文档

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

BabelDOC 是一个开源 PDF 翻译工具（项目英文自述为 Yet Another Document Translator）。你给它一份数字版英文 PDF，它会还你两类文件：中英对照 PDF 和单语中文 PDF。翻译前先解析文档结构再重新排版，公式和多栏布局在译文中基本保持原样。适合需要把论文、技术文档读成中文的人，白底黑字的扫描版 PDF 也能处理。

能处理哪类 PDF：四个场景与边界

1. 数字版学术论文（文字可选中）输入是论文、讲义这类矢量 PDF；输出为对照版加单语版，公式、图表原样保留。边界：跨栏、跨页段落的完整支持还在项目计划中，单页过大的页面会被直接跳过。
2. 需要术语统一的技术文档输入含大量专有名词的 PDF，配合 CSV 术语表指定关键译法；输出是全文同一术语译法一致。
3. 扫描版 PDF输入是白底黑字、清晰度尚可的扫描页，需要开启 OCR 兼容参数。效果直接取决于扫描清晰度，彩色或低对比度页面不适合。
4. 只翻部分页，或大文档分块用页面参数只翻指定页（如--pages "1-5,10"）；用分块参数把长文档拆成若干部分分别翻译，完成后自动合并回一份文件。

第一次使用：用两条命令跑通对照文件

如果机器上还没有 uv（一个 Python 包管理工具），先装 uv，然后一条命令安装 BabelDOC：

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

想从源码跑的话，克隆仓库后用 uv 执行：

git clone https://gitcode.com/GitHub_Trending/ba/BabelDOC cd BabelDOC uv run babeldoc --help

翻译本身依赖大语言模型，BabelDOC 支持 OpenAI 兼容接口（本地 Ollama 之类的服务也可以指向）。默认方向是英译中，最小命令如下：

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

关键参数只看三个：

• --files：要翻译的 PDF，可多次指定实现多文件
• --lang-in/--lang-out：源语言与目标语言，默认 en → zh，英译中不用改
• --output：输出目录，不指定时写入当前工作目录

跑完打开输出目录，你会看到一份双语 PDF（默认带水印，--watermark-output-mode=no_watermark可去掉）和一份单语中文 PDF。先打开对照版翻到公式最多的一页，确认版式正常，再继续往下调参数。另注意：README 说明这套命令行接口主要面向调试与集成，需要图形界面时可用 README 中提到的自部署 WebUI 项目。

每个能力在最终文件里的体现

BabelDOC 不是逐字替换：PDF 先被解析成中间表示（一套记录各文本块位置与样式的统一结构），在这套结构上完成翻译，最后再渲染出新的 PDF。流程各环节可以在源码中核对：布局识别在 babeldoc/docvision/，中间表示与翻译、排版阶段在 babeldoc/format/pdf/document_il/。

• 结构解析：布局模型区分标题、正文、脚注、公式区域。效果：译文里各区块位置不挪动，多栏页面仍按正确顺序阅读。
• 公式保护：公式文本先被标记，翻译阶段不会拆散送入模型。效果：公式渲染与原文一致；文档里公式字体特殊时，可加--formular-font-pattern精确标记。
• 术语一致：默认自动从文档中提取候选术语（--no-auto-extract-glossary可关闭），也可用--glossary-files追加 CSV 术语表。效果：同一术语全文译法统一。
• 排版重排：翻译后按原文属性自动选择字体与换行。效果：中文不断词、不跨行拆散，字体风格接近原文。

典型任务怎么做

任务一：把一篇论文翻成中英对照

• 目标：拿到可逐页对照阅读的双语 PDF，公式区域不串位。
• 准备：数字版论文 PDF，一个可被 OpenAI 兼容接口调用的模型。
• 操作：直接用上文最小命令；文档超过 50 页时加--max-pages-per-part 50分块翻译。
• 检查：在对照版里抽查公式最多的一页，确认公式区与正文不重叠；个别阅读器显示异常时，用--enhance-compatibility重跑一次再对比。

任务二：用术语表统一译法

• 目标：产品名、函数名等术语全文固定译法。
• 准备：一个 CSV 文件，含source（源语词条）、target（目标语词条）、tgt_lng（可选，如 zh-CN）三列；格式样例见 docs/example/demo_glossary.csv。
• 操作：运行时追加--glossary-files terms.csv；翻译中命中术语时，该表会随提示词交给模型。
• 检查：在译文里全文搜索几个关键术语，确认译法没有前后不一致。

任务三：处理扫描版 PDF

• 目标：让扫描文档得到可读的中文译文。
• 准备：页面为白底黑字、扫描较清晰；该参数只在这个前提下有效。
• 操作：运行时追加--ocr-workaround（译文下方加白色块盖住原文，文字统一为黑色）；也可以加--auto-enable-ocr-workaround，让程序检测到大量扫描页后自动开启。
• 检查：看译文的页面背景，原文是否被白块盖住、新文字是否清晰；扫描本身模糊的，参数救不了，建议先换更清晰的源文件。

卡住时先看哪里

• 译文空白或文字选不中先查：原 PDF 的文字能否选中（随手复制一段试试）。再试：加--disable-rich-text-translate简化翻译输入。仍不行换--enhance-compatibility整体开启兼容模式。
• 公式变形、乱码先查：公式是否为矢量文本（可复制选中）。再试：加--formular-font-pattern指明公式字体，或加--remove-non-formula-lines清理干扰段落的装饰线。
• 表格错位表格翻译目前是实验功能（--translate-table-text，默认关闭）；复杂表格建议保留原文，人工核对译文正文。
• 某个阅读器里页面错乱先试--enhance-compatibility；注意其中--skip-clean会让输出文件明显变大。
• 速度太慢确定不是扫描件就加--skip-scanned-detection；大文档用--max-pages-per-part分块；并发可调--pool-max-workers与--qps。
• 启动时报模块缺失、模型或字体下载失败先查网络；用babeldoc --warmup可只下载并校验全部依赖。断网环境先在联网机器打包，再带到目标机器恢复：

babeldoc --generate-offline-assets ./offline_pkg/ babeldoc --restore-offline-assets ./offline_pkg/

仍解决不了时，到项目 Issue 提交（入口见 README.md 的贡献说明），附上可复现的 PDF 样本和完整命令。完整参数清单以 README 为准。

继续深入

• 处理流程逐阶段讲解（解析、段落识别、公式、排版等）：docs/ImplementationDetails/
• 支持的语言列表及连字差异：docs/supported_languages.md
• 翻译引擎源码：babeldoc/translator/
• 术语表加载逻辑：babeldoc/glossary.py

先拿一份几页的短 PDF 跑通最小命令，确认对照文件打开正常后，再叠加术语表、页面范围这些参数。

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