企业官网建设流程全解析

10 分钟跑通 BabelDOC：保留版式的 PDF 翻译指南

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

手头有一份英文论文，想变成中文版，但用在线工具一翻，双栏排版、图表位置和公式全部错位，只能手动重排。BabelDOC 就是为解决这类 PDF 翻译问题做的命令行工具：它先解析 PDF 的版式结构，再把译文填回原位，输出时原段落和译文并排，不需要重排。

装之前，先确认三件事

BabelDOC 适合"文本可选中"的电子 PDF，输出结果保留原文版式，并能同时产出双语对照版和纯译文版。开始之前确认你的机器满足以下条件：

• Python：3.10 ~ 3.13，推荐 3.12
• 系统：Windows、Linux、macOS 均可
• 内存：4GB 以上，处理长文档建议 8GB
• 磁盘：预留 2GB 左右，用于模型与字体资源

如果你的机器只有旧版 Python 且不方便升级，可以先跳过安装。

一行命令装好 BabelDOC

最省事的方式是用 uv（一个快速的 Python 包管理工具）。先按官方提示装好 uv 并配置好 PATH，然后执行：

uv tool install --python 3.12 BabelDOC # 安装到独立环境 babeldoc --help # 验证安装成功

看到参数说明列表就说明装好了。接下来需要一个 API Key：BabelDOC 走 OpenAI 兼容接口，OpenAI 官方控制台、DeepSeek、智谱等平台都能申请，拿到后填进命令的--openai-api-key即可，对应的服务地址填--openai-base-url。

第一次翻译：从命令到双语文档

把下面命令里的 PDF 路径、API Key 换成自己的，就能跑通第一批翻译：

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

几个关键参数：

• --openai：声明使用 OpenAI 兼容接口，翻译服务必须显式开启
• --openai-model/--openai-base-url：指定模型和服务地址，两者要配套
• --files：输入的 PDF 路径；要批量文档翻译，重复传多次--files即可
• --output：结果目录，缺省为当前目录

运行结束后，输出目录里会得到两个 PDF：一份是原文页与译文页并排的双语对照版，一份是纯译文版。

默认方向是英文翻中文，首次使用不需要额外设置。

调翻译效果：三个维度各调一个

语言方向。非默认方向时用--lang-in和--lang-out指定语言代码，比如--lang-in ja。中英方向已打磨得较熟，其他语种组合建议先拿几页试翻。

版式排版。个别 PDF 在阅读器里显示异常时，加--enhance-compatibility一次性打开所有兼容性选项；只翻指定页面用--pages "1-5"，长文档怕内存吃紧时加--max-pages-per-part 50，按 50 页一段切分、译完自动合并。

速度与成本。--qps是每秒发给翻译接口的请求数上限，默认 4；密钥配额充裕、想跑得快就调大，接口限流频繁就调小。--ignore-cache可强制绕过缓存重新翻译，适合改了术语表之后重跑同一批文档。

# 只翻前 10 页，并提高并发 babeldoc --openai --openai-model gpt-4o-mini \ --openai-base-url "https://api.openai.com/v1" \ --openai-api-key "你的密钥" \ --files example.pdf --pages "1-10" --qps 8

复杂场景不想每次敲一长串参数，可以用--config传一个 TOML 配置文件，命令行和配置文件可以混用。

踩坑速查

接下来

第一次跑通后，建议拿一份带术语表的文档验证一致性：CSV 里按source,target,tgt_lng三列整理词条，用--glossary-files传入即可（示例见 docs/example/demo_glossary.csv）。更完整的参数说明可以翻 官方文档。本文按当前稳定版行为编写，各参数默认值以babeldoc --help的输出为准。

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