企业官网建设流程全解析

BabelDOC：三步完成 PDF 翻译排版不塌的完整入门教程

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

读完本文约十分钟，你可以把一篇英文论文翻译成中文版，公式、表格和双栏位置都跟原稿一致。BabelDOC 是一个开源的 PDF 翻译工具，它只替换页面上的文字内容，不改动原版式，最终同时产出单语译文和双语对照两份 PDF。

📋 前置条件：需要准备三样东西

• uv：一个比 pip 快的 Python 包管理工具，用来安装 BabelDOC，按官方说明装好并配置 PATH 即可。
• 一个 OpenAI 协议的模型服务：OpenAI 官方、DeepSeek、GLM 或本地 Ollama 都可以，需要一个 API key。
• 一份待翻译的英文 PDF：建议先拿一篇结构复杂的（比如双栏论文）试手，效果差距看得最明显。

🚀 安装并首次跑通

三步走完，从安装到拿到结果文件。

第一步，安装。

uv tool install --python 3.12 BabelDOC

这条命令把 BabelDOC 连同依赖装进独立的 uv 工具环境，装完系统里会多出一个babeldoc命令。

babeldoc --help

能看到参数列表就说明安装成功。

第二步，首次翻译。

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

参数里指定待翻文件和 LLM 端点即可启动，语言方向默认英译中（--lang-in默认 en、--lang-out默认 zh），不用额外声明。

第三步，验证产出。

跑完当前目录会多两个 PDF：一份纯译文版，一份原文与译文并排的双语对照版，默认带 BabelDOC 水印。效果类似下图，公式f(x)=3x+1这类内容原样保留在对应位置：

🧭 按用途选路：四个常见任务

跑通之后，下面四个任务覆盖了绝大多数实际使用场景，每个只需加一两个参数。

只翻几页试水，确认效果再全量跑

babeldoc --files example.pdf -p "1,3,5-10" -o ./out # 其余 openai 参数同上

-p只翻指定的页码，-o把结果落到指定目录，适合先花几毛钱验证排版质量。

长文档里的术语要钉死译法

把词条写成 CSV（三列：source原词、target译文、tgt_lng可选目标语言），仓库里有现成格式 docs/example/demo_glossary.csv：

babeldoc --files paper.pdf --glossary-files glossary.csv # 其余参数同上

翻译时工具会检查段落命中了哪些词条，命中的术语表连同"按表翻译"的指令一起进入提示词。术语表名称取文件名（去扩展名），默认还会自动从文档抽取高频术语，不想用它可加--no-auto-extract-glossary关闭。

几百页的大文档，防止内存爆掉

babeldoc --files big.pdf --max-pages-per-part 50 # 其余参数同上

工具按 50 页一块自动切分、逐块翻译，结束后自动合并回一份完整 PDF，不需要手动切片再拼。

扫描版 PDF（文字是图片不是文本）

纯文字路径救不了扫描件，两个开关按情况选：

• --ocr-workaround：适用于白底黑字扫描件，在原文位置垫白色矩形遮住原字，译文强制纯黑，视觉上等同重印了一页。
• --auto-enable-ocr-workaround：不确定扫描比例时用它，检测到大量扫描页后自动启用 OCR 处理。

🧩 核心机制：为什么排版不塌

结论一句话：BabelDOC 不直接翻译 PDF，而是先把整页解析成带坐标、字体和样式信息的一份中间表示，翻译只替换其中的文字，再基于这份表示重新渲染出 PDF。

这就像电影配音：画面、字幕位置、镜头切换一概不动，只替换音轨。版面就是"画面"，文字是"音轨"，换掉音轨不影响画面构图。

具体一点说，版面检测会先区分正文、图、表和公式区域，公式压根不进翻译环节；译文回来时按原文档的字号和颜色重新排版，放回原来的位置。所以下面这种左右并排的双语效果里，两栏还是两栏，公式还待在原位：

每个阶段的实现细节写在 docs/ImplementationDetails/，按解析、段落识别、样式与公式、翻译、排版的执行顺序排列；解析入口在 babeldoc/format/pdf/document_il/ 目录。

🩺 排障速查

参数实在太多的时候，可以把配置写进 TOML 文件，用--config config.toml加载，完整模板在 README.md 的 Configuration File 一节，适合做成可复用的自动化流水线。

📚 深入与下一步

• 完整文档站：docs/，由 mkdocs.yml 驱动，支持语言列表见 docs/supported_languages.md
• 各阶段实现细节：docs/ImplementationDetails/
• 翻译示例配置：examples/
• 术语表样例：docs/example/demo_glossary.csv
• 贡献指南：docs/CONTRIBUTING.md

下一步建议：挑一篇你读过的英文双栏论文，跑一次不带任何进阶参数的默认翻译，对照原稿给自己定一个"排版能不能接受"的基准，再决定是否启用术语表和分块配置。

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