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)3x1这类内容原样保留在对应位置 按用途选路四个常见任务跑通之后下面四个任务覆盖了绝大多数实际使用场景每个只需加一两个参数。只翻几页试水确认效果再全量跑babeldoc --files example.pdf -p 1,3,5-10 -o ./out # 其余 openai 参数同上-p只翻指定的页码-o把结果落到指定目录适合先花几毛钱验证排版质量。长文档里的术语要钉死译法把词条写成 CSV三列source原词、target译文、tgt_lng可选目标语言仓库里有现成格式 docs/example/demo_glossary.csvbabeldoc --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/ 目录。 排障速查现象原因解法双语 PDF 在某些阅读器里版面是碎的阅读器对复杂内容流支持不好加--enhance-compatibility一次性打开跳过 PDF 清理、译文页在前、禁用富文本翻译三个开关--openai-base-url指向私有端点报格式错误只兼容 OpenAI 协议的 API换兼容协议的中转如 litellm或换支持该协议的模型本地 Ollama 的 API key 随便填个值改了提示词译文却跟上次一样相同文本命中本地翻译缓存加--ignore-cache强制重新翻译输出文件带 BabelDOC 水印默认水印模式为watermarked--watermark-output-mode no_watermark出干净版both同时输出带与不带水印两份翻得很慢怀疑卡死QPS 默认 4大文档被限速--qps 10 --pool-max-workers 8提到匹配 API 配额的并发进度按--report-interval默认 0.1 秒间隔报告有输出就是活着参数实在太多的时候可以把配置写进 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考