BabelDOC 中间层翻译器ILTranslator深度解析占位符驱动的 PDF 版式保持翻译架构【免费下载链接】BabelDOCYet Another Document Translator项目地址: https://gitcode.com/GitHub_Trending/ba/BabelDOCBabelDOC 的中间层翻译器Intermediate Layer Translator简称 ILTranslator负责在公式与样式处理完成后对文档进行翻译但不破坏版式的核心翻译环节。本文以官方实现文档 docs/ImplementationDetails/ILTranslator/ILTranslator.md 为主体骨架结合仓库内 il_translator.py 源码完整讲解占位符机制、并发翻译流水线、翻译结果还原与调试跟踪机制并给出可落地的TranslationConfig配置实践。读完本文你将掌握 BabelDOC 如何在保留公式、富文本样式与文档结构的前提下完成高质量翻译以及如何通过配置参数控制并发、QPS 与调试行为。背景与目标在 BabelDOC 的流水线中公式和样式处理完成之后需要把文档正文翻译成目标语言。这一阶段最大的难点在于PDF 段落中往往混合着普通文本、数学公式、带特殊样式的富文本等多种成分直接对整个段落做翻译必然破坏公式与排版。ILTranslator 通过占位符Placeholder替换 样式保持的组合技术来解决这一复杂任务核心目标如下与官方文档一致翻译文本的同时保持文档结构不变完整保留公式与特殊格式正确处理带不同样式的富文本支持并发翻译以提升性能。从源码结构看ILTranslator类的stage_name被定义为Translate Paragraphsil_translator.py它会以DocumentIL 中间表示为输入逐页逐段处理并写回翻译结果是整个翻译流水线的核心中间环节。翻译流程总览官方文档将翻译过程划分为四个步骤源码translate()方法il_translator.py印证了这一结构翻译准备Translation Preparation处理段落跳过竖排文本区分单组件段落与多组件段落翻译输入创建Translation Input Creation分析段落组件为公式和富文本生成占位符翻译执行Translation Execution通过线程池并发调用翻译引擎受 QPS 限流控制翻译输出处理Translation Output Processing解析翻译结果按占位符还原公式与样式重建段落组件。下面逐步骤结合源码展开。Step 1翻译准备对应源码pre_translate_paragraph()il_translator.py跳过竖排文本if paragraph.vertical: return None, None直接返回竖排段落不参与翻译记录段落原文tracker.set_pdf_unicode(paragraph.unicode)将原始 Unicode 写入跟踪器字体映射表选择若段落属于某个 XObject则使用该 XObject 的字体映射表page_xobj_font_map富文本翻译开关当翻译引擎不支持 LLM 翻译support_llm_translate为假时强制禁用富文本翻译disable_rich_text_translate True避免引擎无法理解样式标签最短长度过滤当文本长度小于min_text_length默认 5时跳过翻译。在translate()主流程中还会先查找文档第一个layout_label title的段落find_title_paragraphil_translator.py将其快照存入shared_context_cross_split_part作为后续 LLM 提示词中的全局标题上下文。Step 2翻译输入创建占位符机制对应get_translate_input()il_translator.py。这是整个 ILTranslator 最核心的逻辑。前置过滤纯数字段落is_pure_numeric_paragraph见 paragraph_helper.py与纯占位符段落is_placeholder_only_paragraph见 paragraph_helper.py直接跳过无需翻译。单组件段落如果段落只有一个PdfParagraphComposition且由行、同样式字符或单字符组成则直接以整段 unicode 作为翻译输入不套占位符如果该组件是纯公式pdf_formula则跳过公式不需要翻译如果是调试插入字符pdf_same_style_unicode_characters同样跳过。多组件段落遍历段落中的每个组件按类型处理pdf_line/pdf_character普通文本字符直接并入待翻译字符串pdf_formula调用create_formula_placeholder()生成公式占位符并把占位符文本插入待翻译字符串pdf_same_style_characters富文本先做样式判定满足以下任一条件则视为与基准样式一致直接并入文本无需占位符is_same_style()字体、字号、图形状态与段落基准样式完全相同layout_helper.pyis_same_style_except_size()字号差异在 0.71.3 倍之间可能是首字母放大的效果layout_helper.pyis_same_style_except_font()且字体映射后为同一字体除字体外样式一致且映射后fonta.font_id fontb.font_idlayout_helper.py。否则调用create_rich_text_placeholder()生成富文本占位符一左一右两个标记。占位符唯一性保证create_formula_placeholder()与create_rich_text_placeholder()il_translator.py会用正则检查占位符是否与段落已有文本冲突若冲突则id 1递归重试确保每个段落内占位符唯一。占位符 ID 递增规则公式占位符占用 1 个 IDplaceholder_id 1富文本占位符占用 2 个 ID左、右各一placeholder_id 2。占位符数量保护当占位符数量超过 40 个时说明该段落样式碎片化严重递归调用get_translate_input(..., disable_rich_text_translateTrue)禁用富文本翻译退化为纯文本翻译并记录 warning 日志。占位符的实际格式由翻译引擎决定。以仓库内置的OpenAITranslator为例translator.py公式占位符{v1}正则{\s*v\s*1\s*}富文本左占位符style id1右占位符/style。翻译引擎通过get_formular_placeholder()、get_rich_text_left_placeholder()、get_rich_text_right_placeholder()三个接口提供占位符及其正则模式BaseTranslator的默认实现是b1.../b1风格translator.py。Step 3翻译执行并发与 QPS 控制对应translate()与translate_paragraph()il_translator.py。并发模型使用PriorityThreadPoolExecutor见 priority_thread_pool_executor.pymax_workers取自translation_config.pool_max_workers默认等于 QPS 值。每个段落作为一个任务提交到线程池任务优先级为1048576 - paragraph_token_count即token 越少的段落优先级越高优先处理短段落。QPS 限流所有翻译请求经过BaseTranslator.translate()/llm_translate()中共享的RateLimitertranslator.py。RateLimiter采用漏桶算法leaky bucketmin_interval 1.0 / max_qps使用time.monotonic()单调时钟保证线程安全且不受系统时间跳变影响。main.py在启动时通过set_translate_rate_limiter(args.qps)设置全局限流main.py。两种翻译通道do_llm_translate()支持 LLM 的引擎走此通道输入是完整的提示词见下文提示词模板do_translate()普通引擎通道输入是纯文本。OpenAITranslator对 LLM 通道设置temperature0代码注释明确随机采样可能会打断公式标记并对 RateLimitError 做最多 100 次指数退避重试translator.py。内容过滤处理若引擎抛出ContentFilterErrorOpenAI 的敏感内容拦截则在段落下方追加一条灰色提示文本翻译服务检测到内容可能包含不安全或敏感内容……add_content_filter_hintil_translator.py而不是中断整个任务。翻译结果清洗translated_text re.sub(r[. 。…]{20,}, ., translated_text)将超过 20 个连续标点压缩为单个句号用于清理 LLM 可能输出的重复标点。提示词模板PROMPT_TEMPLATEil_translator.py由四块拼接Role 块默认You are a professional {lang_out} native translator...可通过custom_system_prompt覆盖Rules 块要求保持结构不变、不增删/重排任何标签占位符、不翻译code…/code内容、不翻译{v1}/%s/[[...]]等占位符Glossary 块_build_glossary_block()从缓存词表_cached_glossaries中筛选与当前文本相关的条目生成 Markdown 表格Context 块_build_context_block()提供全文首个标题与最近标题作为上下文若开启add_formula_placehold_hint还会附上公式占位符的原文提示。Step 4翻译输出处理占位符还原对应parse_translate_output()il_translator.py与post_translate_paragraph()il_translator.py。无占位符情况如果翻译输入没有占位符直接把整段输出作为PdfSameStyleUnicodeCharacters样式继承段落基准样式。有占位符情况为每个占位符构造正则模式——公式占位符匹配(pattern)富文本占位符匹配(left.*?right)——合并为一个组合正则通过re.finditer扫描翻译输出占位符之间的普通文本生成基准样式的 Unicode 组件命中公式占位符将原文的PdfFormula对象原样挂回组件comp.pdf_formula placeholder.formula保证公式完整性和定位不变命中富文本占位符提取左右占位符之间的文本若翻译结果与原文一致则直接复用原PdfSameStyleCharacters样式完全保持否则生成一个继承该组件样式的 Unicode 组件。幻觉占位符清理remove_placeholder()il_translator.py会先用占位符正则把残留标记清空再检测形似公式/富文本占位符的 token只保留允许集合原文自带的占位符 token 注入的占位符中的内容其余疑似 LLM 幻觉生成的占位符一律删除并记录到跟踪器record_removed_hallucinated_placeholder。样式兜底还原完成后若某个 Unicode 组件的样式为 None则回填段落基准样式paragraph.pdf_style。附加特性样式保持通过与基准样式的三类对比is_same_style/is_same_style_except_size/is_same_style_except_font智能判断哪些富文本无需占位符最大限度降低 LLM 破坏样式的风险翻译结果统一通过PdfSameStyleUnicodeCharacters承载样式信息随组件保留供后续排版阶段使用。公式处理公式通过{v1}类占位符整体保护翻译期间不被 LLM 改写翻译输出解析时按占位符 ID 精确还原原始PdfFormula保持公式字符与定位get_placeholders_hint()还会为公式占位符附带原文提示过滤掉超过 80% 字符为(cid:\d)的无法翻译公式仅在开启add_formula_placehold_hint时注入提示词。调试支持翻译跟踪与 JSON 输出源码内置了四级跟踪器DocumentTranslateTracker→PageTranslateTracker→ParagraphTranslateTracker→LLMTranslateTrackeril_translator.py。DocumentTranslateTracker维护page、cross_page、cross_column三个维度ParagraphTranslateTracker记录输入、输出、占位符、原始占位符 token、被删除的幻觉占位符、多段合并 ID 等LLMTranslateTracker记录提示词输入/输出、是否报错、占位符是否全部命中、是否回退到简单翻译。当debugTrue或设置了working_dir时translate()会把整个跟踪树序列化为translate_tracking.json写入工作目录il_translator.pyJSON 结构包含cross_page/cross_column/page三类段落记录字段含input、output、pdf_unicode、llm_translate_trackers、placeholders、multi_paragraph_id等便于逐段排查翻译质量问题。LLM Only 批量翻译模式仓库还提供ILTranslatorLLMOnlyil_translator_llm_only.py以 JSON 数组批量翻译将同一批段落打包为 JSON 输入每个元素含id、input、layout_label要求 LLM 原样返回相同长度的 JSON只保留id并新增output支持跨页段落合并上一页末尾正文 下一页开头正文与跨栏段落合并同页内相邻正文 y2 间距大于 20 的段落视为分栏切断对输出做质量校验与输入完全相同且 token 数 10、输出/输入 token 比不在 0.33 区间、编辑距离过小 5 且输入 token 20等情况都会触发回退——将段落重新提交给基础ILTranslator.translate_paragraph走简单翻译通道并统计ok_count/fallback_count/total_count。局限性与边界官方文档明确列出的限制如下结合源码均能得到印证竖排文本不支持pre_translate_paragraph直接跳过paragraph.vertical段落复杂嵌套样式可能无法完美保留富文本占位符仅用左右两个标记包裹整段样式文本深层嵌套样式的细节可能丢失占位符数量超过 40 个时还会整体禁用富文本翻译占位符冲突在极少数情况下可能发生虽然有唯一性递归检查但极端文本仍可能出现碰撞翻译质量取决于外部翻译引擎ILTranslator 只负责结构保护最终译文质量由BaseTranslator实现如 OpenAI 系列决定。配置选项TranslationConfig翻译过程通过TranslationConfigtranslation_config.py定制核心参数如下参数默认值说明qps1CLI 默认4翻译请求每秒最大查询数直接决定RateLimiter的min_interval1.0 / qpspool_max_workers等于qps内部线程池含段落翻译、术语提取的最大工作线程数可直接覆盖 QPS 推导值term_pool_max_workers等于pool_max_workers自动术语提取专用线程数debugFalse开启调试日志并将工作目录固定到缓存目录working_dir临时目录工作目录设置后translate_tracking.json会被写入其中min_text_length5少于该长度的段落跳过翻译disable_rich_text_translateFalse全局禁用富文本占位符翻译ocr_workaroundTrue时被强制开启ocr_workaroundFalse开启时同时跳过扫描检测并禁用富文本翻译enhance_compatibilityFalse兼容性模式同时置skip_clean、dual_translate_first、disable_rich_text_translate为真custom_system_promptNone自定义 LLM 角色提示词自动追加 Follow all rules strictly.add_formula_placehold_hintFalse是否在提示词中附带公式占位符原文提示默认关闭可能影响翻译质量auto_extract_glossaryTrue自动术语提取开关skip_translation/only_parse_generate_pdf时强制关闭glossariesNone用户词表列表命中词表的术语强制使用目标译文disable_same_text_fallbackFalse关闭LLM 输出与输入完全相同则回退的行为skip_translation/only_parse_generate_pdfFalse跳过翻译 / 仅解析生成 PDFreport_interval0.1进度上报间隔秒对应 CLI 参数见 main.pybabeldoc --input paper.pdf --lang-in en --lang-out zh \ --qps 4 \ --debug \ --disable-rich-text-translate \ --min-text-length 5 \ --pool-max-workers 8 \ --custom-system-prompt You are a technical translator for academic papers.其中--qps控制翻译服务限流main.py--pool-max-workers直接设置内部任务处理线程数main.py。配置落地时注意TranslationConfig.__init__中pool_max_workers默认取qps值translation_config.pymin_text_length默认 5translation_config.py因此调大 QPS 的同时会同步放大并发度需结合翻译服务端的限流承受能力一起评估。小结ILTranslator 以占位符替换 并发翻译 占位符还原三阶段流水线为核心在 BabelDOC 中承担了翻译但不破坏版式的关键职责公式用{v1}类占位符整体保护富文本用style标签对包裹并保留原样式纯文本直接翻译同时通过PriorityThreadPoolExecutor并发与漏桶RateLimiter限流保证吞吐与稳定性。配合translate_tracking.json跟踪输出和TranslationConfig的精细参数qps、pool_max_workers、min_text_length、disable_rich_text_translate、debug等开发者可以系统性地定位翻译质量问题并调优性能。相关实现细节可继续阅读 il_translator.py、il_translator_llm_only.py 与 translation_config.py。【免费下载链接】BabelDOCYet Another Document Translator项目地址: https://gitcode.com/GitHub_Trending/ba/BabelDOC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考