DocuTranslator技术原理解析

DOCX 英译中原理适用于DocxWorkflow+DocxTranslator+Docx2DocxExporter链路，实现在保持原始格式的前提下，将 DOCX 中的英文翻译为中文并可选的将译文插入原文下方。整体架构.docx 文件 │ ▼ DocxWorkflow.read_path() Document (content=bytes) │ ▼ DocxTranslator.translate() │ ├── 1. _pre_translate() → 解析 .docx → 提取文本段 ├── 2. send_segments() → 文本分片 → LLM 并发翻译 └── 3. _after_translate() → 回写译文 → 保存为 .docx bytes │ ▼ Docx2DocxExporter.export() │ ▼ Document(content=bytes) │ ▼ save_as_docx() / export_to_docx() .docx 文件（格式保留）核心设计哲学：在 OOXML 的 XML 层操作，不依赖中间格式（不转 Markdown/HTML）。利用 XML 深拷贝保留所有格式信息，只修改文本节点的内容。一、文档分割（如何拆解 .docx）拆分分两个层次：文档结构的遍历和文本段的分片。1.1 文档结构遍历代码遍历整个文档对象树，提取所有可翻译的文本段：body（正文区域） ├── w:p 段落 │ └── Run 序列 → 分组为文本段（segment） ├── w:tbl 表格 │ └── 单元格 w:tc → 递归遍历内部段落 ├── w:sdt 内容控件 → 递归遍历 └── 超链接/修订标记/智能标签 → 递归遍历 页眉/页脚 ├── section.header ├── section.footer ├── section.first_page_header / .first_page_footer └── section.even_page_header / .even_page_footer 脚注/尾注 ├── doc.part.footnotes_part └── doc.part.endnotes_part遍历中的过滤规则标签处理方式原因w:proofErr忽略拼写/语法检查标记，不是正文w:lastRenderedPageBreak忽略渲染分页符，不是文本w:bookmarkStart/w:bookmarkEnd忽略书签标记w:commentRangeStart/w:commentRangeEnd忽略批注范围标记w:del/w:moveFrom/w:moveTo忽略修订删除/移动的内容w:smartTag递归遍历智能标签内包裹着文本w:sdtContent递归遍历内容控件内包裹着文本w:hyperlink递归遍历超链接文本需要翻译w:ins递归遍历修订插入的内容需要翻译w:fldChar(begin/end)中断当前段域代码（目录TOC、页码PAGE）的指令部分跳过文本框支持w:txbxContent（文本框）中的文本会被提取并翻译。常见于流程图的文字标注、侧边栏等。1.2 文本段的粒度控制一个段落内部通常有多个w:r（Run），每个 Run 有自己的格式属性。翻译时不能简单按 Run 切分，否则会破坏句子的完整性。Run 分组策略w:pw:rw:rPrw:b//w:rPrw:tHello/w:t/w:rw:rw:rPrw:b//w:rPrw:tworld,