BabelDOC PDF翻译实战指南5 分钟出双语版扫描件、离线场景全覆盖【免费下载链接】BabelDOCYet Another Document Translator项目地址: https://gitcode.com/GitHub_Trending/ba/BabelDOC拿到一份几百页的英文论文 PDF想保留版式翻译往往卡在三处在线工具把版式拆得七零八落OCR 只吐出一堆纯文本术语翻到后半本又换了说法。BabelDOC 就是干这个的 PDF 翻译工具——它先解析出 PDF 的原始版面把文本送进 LLM 翻译再把译文重新排版回填到原位置一次产出双语对照版和纯翻译版两种 PDF适合翻译论文、手册等版式要求高的文档。下面按实际使用路径走一遍装好、接上模型、调兼容、救扫描件、离线部署。5 分钟装好翻出第一份双语 PDF安装一行命令的事项目要求 Python 3.10 以上官方推荐 3.12uv tool install --python 3.12 BabelDOC babeldoc --files paper.pdf --openai --openai-api-key sk-xxx --openai-model gpt-4o-mini源语言、目标语言默认就是英文到中文不用指定。跑完后默认同时产出两种文件纯翻译版和双语对照版想要哪边缺哪边就加--no-mono或--no-dual。输出目录默认跟输入文件同处用--output可以改。想从源码跑也行git clone https://gitcode.com/GitHub_Trending/ba/BabelDOC进目录后uv run babeldoc参数完全一样。参数多到记不住时用 TOML 配置文件README 里有完整示例命令行只传-c 路径[babeldoc] openai true openai-model gpt-4o-mini openai-api-key sk-xxx qps 4接上模型云 API 到本地 OllamaBabelDOC 只认一种翻译服务OpenAI 兼容 API。也就是说它只需要 API key 和 base URL 两样东西OpenAI 官方、Azure、各家模型网关、自托管推理服务都能接。几种常见接法官方 OpenAI--openai-base-url https://api.openai.com/v1模型不写就是默认的gpt-4o-mini本地 Ollamabase URL 填http://localhost:11434/v1API key 随便填个占位值就行自托管 vLLMbase URL 指向http://localhost:8000/v1模型名和加载的一致速度由两个参数控制。--qps是每秒请求上限默认 4内部用漏桶算法按固定节奏放行请求的限流方式保证请求平滑不扎堆--pool-max-workers是内部任务线程数不写就等于 QPS 值。API 额度宽裕的话两个一起加比如 qps 10、workers 10。可靠性是内建的temperature 固定为 0避免随机采样打断公式占位符遇到限流错误会自动按指数退避重试最长 100 次单次等待 1 到 15 秒大文档不会因为偶发 429 直接中断。结果会写进本地 SQLite 缓存缓存键绑定了模型名、提示词、语言对等影响结果的参数——同一段文本第二次翻译不再消耗 token。改了模型发现结果没变加--ignore-cache强制重翻。任务结束日志里会输出 token 消耗统计prompt、completion、缓存命中各一份方便算成本。针对特定模型想改系统提示词用--custom-system-prompt整体覆盖常见用途是给 Qwen3 加/no_think指令跳过推理比如--custom-system-prompt /no_think You are a professional, authentic machine translation engine.。阅读器显示异常一个开关先救回来有些 PDF 阅读器吃不了清理后的文档结构打开就是乱码或崩溃。BabelDOC 给了三个独立开关也可以用--enhance-compatibility一键全开开关作用代价--skip-clean跳过移除冗余资源、压缩字体的 PDF 清理步骤文件体积变大--dual-translate-first双语版里译文页排在原文页前面无--disable-rich-text-translate翻译输入里去掉格式占位符简化处理粗体斜体等样式映射会少一些碰到兼容问题先试--enhance-compatibility再逐关排查。输出形态还有几个常用项--watermark-output-modewatermarked默认带水印/no_watermark/both两个版本都输出--use-alternating-pages-dual双语模式下原文页和译文页交替排列而不是并排展示手机上翻页看更顺--primary-font-family指定译文主字体三选一serif/sans-serif/script默认按原文字体属性自动匹配--pages只翻指定页写法如1,2,1-,-3,3-5配合--only-include-translated-page输出 PDF 里也只保留这些页让扫描件也能稳定出稿扫描版 PDF 是特例文字本质是图片译文压上去容易和原文糊在一起。BabelDOC 给了三个专门开关--ocr-workaround给译文下方垫白色背景矩形盖住原文文字统一强制为黑色。前提假设是白底黑字黑白扫描件最合适--auto-enable-ocr-workaround自动判断超过 80% 的页面被识别为扫描页就自动启用上面的方案不用你自己预判--skip-scanned-detection确定是电子文档时跳过扫描检测省掉这一步的时间建议默认走自动检测确认是黑白扫描、结果还糊的时候再手动开--ocr-workaround。注意这三个开关有联动关系开了--auto-enable-ocr-workaround后它会根据检测结果接管另外两个的值所以别三个同时写死。大论文先切片再翻长文档一次性解析内存和时间都吃紧。--max-pages-per-part 50会把文档按 50 页一份切块逐份翻译完成后自动拼回一个文件大文件建议直接带上。相关配置--working-dir指定工作目录默认用系统临时目录磁盘紧张就指到大容量分区--min-text-length短于这个字符数的碎片不送翻默认 5避免一堆页码、孤立符号也发请求--formular-font-pattern/--formular-char-pattern自定义公式识别的字体名和字符正则论文里的公式没被认出时用它补规则让术语全文一致术语表加自动提取LLM 自由发挥的代价是同一个术语200 页里可能出现三种译法。BabelDOC 有两道防线。第一道是用户术语表。CSV 格式两列必填一列可选列名说明必填source源语言术语是target目标语言译法是tgt_lng目标语言代码如 zh-CN填了则只有与--lang-out匹配时才加载否--glossary-files terms.csv,acronyms.csv一次挂多个文件。匹配走 hyperscan 引擎一个为海量正则快速扫描设计的库不区分大小写长术语优先命中几千条起步没有压力。当前段落里出现表内术语时这份术语会被塞进 LLM 的提示词强制要求遵守。第二道是自动提取默认开启。翻译过程中额外用 LLM 扫一遍段落挑出实体和反复出现的核心名词生成术语对同一术语被提取出多个译法时保留出现次数最多的那个。加--save-auto-extracted-glossary会把提取结果存成 CSV 落到输出目录下次翻译可以直接拿它当种子表。优先级从高到低用户术语表 自动提取术语 LLM 自由翻译。不想要自动提取的开销--no-auto-extract-glossary关掉--openai-term-extraction-model还能给提取单独指定一个便宜模型主力模型专心翻译。离线部署内网服务器也能跑内网环境装不上模型和字体官方方案是离线资源包babeldoc --generate-offline-assets ./pkg babeldoc --restore-offline-assets ./pkg/offline_assets_xxx.zip在有网机器上生成一次得到包含全部 ONNX 版面模型和字体的 zip 包包内所有资产都带 SHA3-256 校验。拷到内网机器 restore 即可restore 也可以直接给目录它会自动找到对应的包文件。注意包文件名不能改——文件名里编码了文件清单哈希。第一次跑之前可以先执行--warmup它只下载并校验全部所需资产然后退出避免正式翻译中途才卡在断网上。常见情况与排错路径想看结果到底差在哪--debug打开调试日志详细中间产物导出到~/.cache/babeldoc/working--show-char-box把字符框画在页面上肉眼看解析有没有跑偏表格里的字没被翻译--translate-table-text是实验特性开启后会额外加载 RapidOCR 模型识别并翻译表格内容429 频繁出现直接调低--qps。内置重试会帮你等但源头降速更有效已知局限官方 README 的 Known Issues 部分作者和参考文献区翻译后可能被并进同一段落线条、首字下沉暂不支持超大页面会被跳过支持哪些语言对见 supported languages目前主要验证过英文到中文想理解内部管线ImplementationDetails 按解析、段落切分、翻译、排版、PDF 生成逐阶段讲解【免费下载链接】BabelDOCYet Another Document Translator项目地址: https://gitcode.com/GitHub_Trending/ba/BabelDOC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 BabelDOC PDF翻译实战指南：5 分钟出双语版，扫描件、离线场景全覆盖
BabelDOC PDF翻译实战指南5 分钟出双语版扫描件、离线场景全覆盖【免费下载链接】BabelDOCYet Another Document Translator项目地址: https://gitcode.com/GitHub_Trending/ba/BabelDOC拿到一份几百页的英文论文 PDF想保留版式翻译往往卡在三处在线工具把版式拆得七零八落OCR 只吐出一堆纯文本术语翻到后半本又换了说法。BabelDOC 就是干这个的 PDF 翻译工具——它先解析出 PDF 的原始版面把文本送进 LLM 翻译再把译文重新排版回填到原位置一次产出双语对照版和纯翻译版两种 PDF适合翻译论文、手册等版式要求高的文档。下面按实际使用路径走一遍装好、接上模型、调兼容、救扫描件、离线部署。5 分钟装好翻出第一份双语 PDF安装一行命令的事项目要求 Python 3.10 以上官方推荐 3.12uv tool install --python 3.12 BabelDOC babeldoc --files paper.pdf --openai --openai-api-key sk-xxx --openai-model gpt-4o-mini源语言、目标语言默认就是英文到中文不用指定。跑完后默认同时产出两种文件纯翻译版和双语对照版想要哪边缺哪边就加--no-mono或--no-dual。输出目录默认跟输入文件同处用--output可以改。想从源码跑也行git clone https://gitcode.com/GitHub_Trending/ba/BabelDOC进目录后uv run babeldoc参数完全一样。参数多到记不住时用 TOML 配置文件README 里有完整示例命令行只传-c 路径[babeldoc] openai true openai-model gpt-4o-mini openai-api-key sk-xxx qps 4接上模型云 API 到本地 OllamaBabelDOC 只认一种翻译服务OpenAI 兼容 API。也就是说它只需要 API key 和 base URL 两样东西OpenAI 官方、Azure、各家模型网关、自托管推理服务都能接。几种常见接法官方 OpenAI--openai-base-url https://api.openai.com/v1模型不写就是默认的gpt-4o-mini本地 Ollamabase URL 填http://localhost:11434/v1API key 随便填个占位值就行自托管 vLLMbase URL 指向http://localhost:8000/v1模型名和加载的一致速度由两个参数控制。--qps是每秒请求上限默认 4内部用漏桶算法按固定节奏放行请求的限流方式保证请求平滑不扎堆--pool-max-workers是内部任务线程数不写就等于 QPS 值。API 额度宽裕的话两个一起加比如 qps 10、workers 10。可靠性是内建的temperature 固定为 0避免随机采样打断公式占位符遇到限流错误会自动按指数退避重试最长 100 次单次等待 1 到 15 秒大文档不会因为偶发 429 直接中断。结果会写进本地 SQLite 缓存缓存键绑定了模型名、提示词、语言对等影响结果的参数——同一段文本第二次翻译不再消耗 token。改了模型发现结果没变加--ignore-cache强制重翻。任务结束日志里会输出 token 消耗统计prompt、completion、缓存命中各一份方便算成本。针对特定模型想改系统提示词用--custom-system-prompt整体覆盖常见用途是给 Qwen3 加/no_think指令跳过推理比如--custom-system-prompt /no_think You are a professional, authentic machine translation engine.。阅读器显示异常一个开关先救回来有些 PDF 阅读器吃不了清理后的文档结构打开就是乱码或崩溃。BabelDOC 给了三个独立开关也可以用--enhance-compatibility一键全开开关作用代价--skip-clean跳过移除冗余资源、压缩字体的 PDF 清理步骤文件体积变大--dual-translate-first双语版里译文页排在原文页前面无--disable-rich-text-translate翻译输入里去掉格式占位符简化处理粗体斜体等样式映射会少一些碰到兼容问题先试--enhance-compatibility再逐关排查。输出形态还有几个常用项--watermark-output-modewatermarked默认带水印/no_watermark/both两个版本都输出--use-alternating-pages-dual双语模式下原文页和译文页交替排列而不是并排展示手机上翻页看更顺--primary-font-family指定译文主字体三选一serif/sans-serif/script默认按原文字体属性自动匹配--pages只翻指定页写法如1,2,1-,-3,3-5配合--only-include-translated-page输出 PDF 里也只保留这些页让扫描件也能稳定出稿扫描版 PDF 是特例文字本质是图片译文压上去容易和原文糊在一起。BabelDOC 给了三个专门开关--ocr-workaround给译文下方垫白色背景矩形盖住原文文字统一强制为黑色。前提假设是白底黑字黑白扫描件最合适--auto-enable-ocr-workaround自动判断超过 80% 的页面被识别为扫描页就自动启用上面的方案不用你自己预判--skip-scanned-detection确定是电子文档时跳过扫描检测省掉这一步的时间建议默认走自动检测确认是黑白扫描、结果还糊的时候再手动开--ocr-workaround。注意这三个开关有联动关系开了--auto-enable-ocr-workaround后它会根据检测结果接管另外两个的值所以别三个同时写死。大论文先切片再翻长文档一次性解析内存和时间都吃紧。--max-pages-per-part 50会把文档按 50 页一份切块逐份翻译完成后自动拼回一个文件大文件建议直接带上。相关配置--working-dir指定工作目录默认用系统临时目录磁盘紧张就指到大容量分区--min-text-length短于这个字符数的碎片不送翻默认 5避免一堆页码、孤立符号也发请求--formular-font-pattern/--formular-char-pattern自定义公式识别的字体名和字符正则论文里的公式没被认出时用它补规则让术语全文一致术语表加自动提取LLM 自由发挥的代价是同一个术语200 页里可能出现三种译法。BabelDOC 有两道防线。第一道是用户术语表。CSV 格式两列必填一列可选列名说明必填source源语言术语是target目标语言译法是tgt_lng目标语言代码如 zh-CN填了则只有与--lang-out匹配时才加载否--glossary-files terms.csv,acronyms.csv一次挂多个文件。匹配走 hyperscan 引擎一个为海量正则快速扫描设计的库不区分大小写长术语优先命中几千条起步没有压力。当前段落里出现表内术语时这份术语会被塞进 LLM 的提示词强制要求遵守。第二道是自动提取默认开启。翻译过程中额外用 LLM 扫一遍段落挑出实体和反复出现的核心名词生成术语对同一术语被提取出多个译法时保留出现次数最多的那个。加--save-auto-extracted-glossary会把提取结果存成 CSV 落到输出目录下次翻译可以直接拿它当种子表。优先级从高到低用户术语表 自动提取术语 LLM 自由翻译。不想要自动提取的开销--no-auto-extract-glossary关掉--openai-term-extraction-model还能给提取单独指定一个便宜模型主力模型专心翻译。离线部署内网服务器也能跑内网环境装不上模型和字体官方方案是离线资源包babeldoc --generate-offline-assets ./pkg babeldoc --restore-offline-assets ./pkg/offline_assets_xxx.zip在有网机器上生成一次得到包含全部 ONNX 版面模型和字体的 zip 包包内所有资产都带 SHA3-256 校验。拷到内网机器 restore 即可restore 也可以直接给目录它会自动找到对应的包文件。注意包文件名不能改——文件名里编码了文件清单哈希。第一次跑之前可以先执行--warmup它只下载并校验全部所需资产然后退出避免正式翻译中途才卡在断网上。常见情况与排错路径想看结果到底差在哪--debug打开调试日志详细中间产物导出到~/.cache/babeldoc/working--show-char-box把字符框画在页面上肉眼看解析有没有跑偏表格里的字没被翻译--translate-table-text是实验特性开启后会额外加载 RapidOCR 模型识别并翻译表格内容429 频繁出现直接调低--qps。内置重试会帮你等但源头降速更有效已知局限官方 README 的 Known Issues 部分作者和参考文献区翻译后可能被并进同一段落线条、首字下沉暂不支持超大页面会被跳过支持哪些语言对见 supported languages目前主要验证过英文到中文想理解内部管线ImplementationDetails 按解析、段落切分、翻译、排版、PDF 生成逐阶段讲解【免费下载链接】BabelDOCYet Another Document Translator项目地址: https://gitcode.com/GitHub_Trending/ba/BabelDOC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考