BabelDOC 完整实战指南如何快速做出保留原排版的 PDF 翻译【免费下载链接】BabelDOCYet Another Document Translator项目地址: https://gitcode.com/GitHub_Trending/ba/BabelDOCBabelDOC 是一款开源的 PDF 翻译工具它解析 PDF 的底层结构把译文重新排回原文的版面位置默认输出一份原文与译文并排的双语 PDF让排版保留和翻译质量同时发生。它特别适合经常阅读英文论文、技术报告和长文档的人目前主要打磨英文转中文方向其他语言对测试较少。装好环境跑通第一份 PDF 环境要求只有一条硬性的Python 3.10 到 3.13。官方推荐用uv这个 Python 包管理器安装一条命令装完uv tool install --python 3.12 BabelDOC babeldoc --help如果要从源码跑比如想提 issue 前先复现一下问题可以克隆仓库后直接用uv run执行git clone https://gitcode.com/GitHub_Trending/ba/BabelDOC cd BabelDOC uv run babeldoc --help第一次翻译的最小命令长这样babeldoc --openai \ --openai-model gpt-4o-mini \ --openai-base-url https://api.openai.com/v1 \ --openai-api-key 你的api-key \ --files paper.pdf--files可以重复写多次来批量处理--openai-base-url可以换成任何 OpenAI 兼容的接口地址所以 DeepSeek、GLM 乃至本地 Ollama 都能接。语言方向默认就是--lang-in en到--lang-out zh不用显式写。跑完后输入目录旁会多出两份文件一份纯译文mono一份原文/译文并排的双语对照版dual用--no-dual或--no-mono可以只保留其中一份。核心功能走读四个真实场景的参数调法公式保护让公式不动、只转文字 数学论文的难点在于公式不能被翻译服务碰坏。BabelDOC 默认通过字体特征识别公式文本并整段跳过绝大多数 Times 数学字体场景开箱即用。如果你的文档用了自定义公式字体可以补两个正则--formular-font-pattern按字体名匹配、--formular-char-pattern按字符集匹配。跑完检查公式区域占位符应原样保留只有周围散文被翻译。顺带一提表格里的文字默认不翻译需要的话加--translate-table-text实验性功能结果要自己核对。术语表让系列文档译法统一一批报告或整本专著最怕同一术语三四种译法。准备一个三列 CSV示例见 demo_glossary.csvsource,target,tgt_lng Transformer,变压器,zh-CN然后传--glossary-files glossary.csv。翻译时工具会检查每个文本段是否命中表内术语命中才把这份表注入提示词模型会按表内译法输出。另外工具默认还会自动抽取高频术语参与翻译想留档就加--save-auto-extracted-glossary会导出 CSV 供你人工修订。扫描版 PDF 的识别与 OCR 兜底扫描件没有真实文本层处理策略不同。已知是电子件时加--skip-scanned-detection跳过扫描检测能省掉一整轮版面分析拿不准时加--auto-enable-ocr-workaround当扫描页占比超过 80% 才自动启用 OCR 兜底。--ocr-workaround则是强制模式在译文下垫白色色块盖住原文、文字统一染黑——注意它假设纯白底 纯黑字彩色扫描件不适用。页码范围与大文档切分只想翻摘要和结论--pages 1,2,1-,-3,3-5支持任意组合的页码表达式配合--only-include-translated-page输出文件就只剩翻译过的那几页。500 页以上的文档建议--max-pages-per-part 50自动切成若干段分别翻译再拼回完整 PDF既避免内存峰值也方便断点重跑某一段。实战细节与常见坑阅读器打开排版异常时切兼容模式⚠️ 个别 PDF 阅读器对译文文件的字体和跨页渲染有兼容问题。官方给的组合拳是--enhance-compatibility它一次性开启--skip-clean、--dual-translate-first、--disable-rich-text-translate三项如果只想精细调可以单独试--skip-clean代价是文件体积变大。译文页默认带水印交付前用--watermark-output-mode no_watermark去掉即可。低配机器的内存优化内存吃紧时把--qps翻译服务的每秒请求上限默认 4调到 2 左右再用--pool-max-workers把内部任务线程数压到 2~4大文档同时上--max-pages-per-part让单段处理量变小内存曲线就平稳了。翻译缓存省钱与重翻的两面已翻译过的文本会写入本地 SQLite 缓存重跑同一文档基本不产生新请求实现见 translator/cache.py。反过来换了模型想全部重翻时记得加--ignore-cache否则你会拿到看起来没生效的旧译文。已知局限如实说作者与参考文献区域翻译后可能被合并成一段线条line和首字下沉元素暂不支持页面尺寸异常大的页会被跳过。这些都在 README.md 的 Known Issues 里有记录。进阶调优配置文件与模型选择⚙️ 所有命令行选项都能写进 TOML 配置文件用-c加载适合固定一套参数反复跑[babeldoc] lang-in en lang-out zh-CN qps 10 output ./out max-pages-per-part 50 watermark-output-mode no_watermark openai true openai-model gpt-4o-mini openai-base-url https://api.openai.com/v1 openai-api-key 你的api-key glossary-files ./glossary.csv模型怎么选参考这张速查表模型选择特点适用gpt-4o-mini默认快、成本低日常论文、快速预览更强的 OpenAI 兼容模型如 deepseek-chat、glm-4-flash术语准确率更高正式交付文档本地模型Ollama 等私有、不依赖外网 APIAPI key 随便填内部资料、离线环境还有两个实用开关--custom-system-prompt可以给翻译提示词追加自定义指令比如某些模型需要关闭思考模式完全断网的环境可以在联网机器上--generate-offline-assets生成模型与字体包目标机器用--restore-offline-assets还原--warmup则只下载并校验资源后退出适合部署前预检。小结BabelDOC 把 PDF 翻译里最头疼的排版保留做成了默认行为公式、表格、图文混排尽量原样保留译文回到原文的位置双语对照随输出附带。当前它最擅长英文转中文的学术与技术文档其余语言对和极端复杂版面仍建议先小样试译。想深入原理或参与贡献可以从 docs/ 的文档站和 实现细节文档 入手核心处理管线在 babeldoc/format/pdf/ 目录下。【免费下载链接】BabelDOCYet Another Document Translator项目地址: https://gitcode.com/GitHub_Trending/ba/BabelDOC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考