文档翻译（保持格式）
能力
- 支持
.docx/.xlsx/.pptx - 提取范围：
- docx：正文
word/document.xml、页眉word/headerN.xml、页脚word/footerN.xml（含脚注/尾注） - pptx：幻灯片
ppt/slides/slideN.xml、备注ppt/notesSlides/notesSlideN.xml - xlsx：共享字符串
xl/sharedStrings.xml、工作表内联字符串xl/worksheets/sheetN.xml - 只替换文本节点的文字内容，标签 / 属性 / 样式 / 排版 / 图片 / 关系 / 其他 XML 字节级保持不变
- 翻译由大模型完成：先理解原文与上下文，再用目标语言自然重写，避免中式英语、避免逐词硬译
前置依赖
- Python 3.10+，需
lxml - 隔离环境（推荐）：
bash python -m venv .venv && .venv/Scripts/pip install lxml - 本技能脚本路径：
scripts/office_translate.py
工作流（四步）
1. 提取文本
python scripts/office_translate.py extract <原文件> -o units.json
产出 units.json，每个可译单元结构：
{
"file": "word/document.xml",
"index": 12,
"run_refs": [12, 13, 14],
"context": "所在段落/文本框/单元格的完整文本（含全部 run，用于翻译理解）",
"source": "同一样式组内合并后的原文"
}
- 分组策略（兼顾"不丢样式"与"翻译不断裂"）：提取时，同一段落/单元格内，格式完全相同（
w:rPr一致）的相邻 run 才合并成一个单元；格式不同的 run 各自独立成单元。 - 好处一：段落内样式零丢失——某个词是粗体/红色/特殊字号，它自成单元，回填后该
<w:rPr>原样保留，不会因合并而被清掉。 - 好处二：拆词被修复——OOXML 常把一个词拆成多个"同样式"的 run（如"添加指"+"纹"），它们同组会被合并翻译，避免英文断裂成
Add Fing+erprint。 - 翻译准确性靠
context：每个单元的context字段是它所在段落/单元格的完整文本（含所有 run），智能体翻译时据此理解整句/整段语境，但只改写本单元source——这样既准确又不会动到别的样式组。 run_refs：本单元覆盖的所有文本节点在该文件内的全局序号。回填时把完整译文写入第一个节点，同组内其余节点文本置空（同组样式一致，清空不影响视觉；节点与属性完整保留）。index等于run_refs[0]，用于兼容旧格式。- 纯数字/标点/空白单元会被自动跳过。
2. 翻译（默认走 A，无需任何 key）
A. 由智能体（大模型）直接翻译 —— 默认路径，不需要任何 API key
这是本技能推荐的流程，翻译由智能体自带的 LLM 能力完成，全程零密钥、零费用。把"分批"和"回收集成"用脚本固化好了，无需手写映射：
# 2.1 把可译单元切成适合大模型一次处理的批次（每批默认 80 条）
# --cjk-only 只挑含中文的单元（中文→英文时用，跳过日期/英文标识等噪声）
python scripts/office_translate.py split units.json --size 80 --out-dir batches --cjk-only
# 2.2 【智能体做这一步】逐批读取 batches/batch_000.json …，
# 把每条 source 按"翻译准则"重写为英文，写出同名 .en.json：
# 原文件 batch_000.json -> 译文 batch_000.en.json（JSON 数组，顺序一致）
# （也可以直接在原 batch 文件里给每条加 "target" 字段，collect 同样认）
# 例：batch_000.en.json = ["Qingsong Partner System", "Version: V1.0", ...]
# 2.3 自动把所有批次的译文按原始 XML 位置汇总成 translated.json
python scripts/office_translate.py collect units.json --batches batches -o translated.json
> 这不需要你提供任何密钥——翻译由智能体自带的 LLM 能力完成。split 解决了"大文档一次翻不完"的问题，collect 负责把译文精准映射回 units.json（按主索引），再交给 apply 回填。
B. 调外部 API 批量自动化（可选）
仅当你希望"无人值守批量跑"时才用，需要提供 OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL（兼容 OpenAI 的任意端点）：
python scripts/office_translate.py translate units.json --src Chinese --tgt English
脚本内置同样的翻译准则提示词，分批调用并返回 units.translated.json。
3. 回填并重新打包
python scripts/office_translate.py apply <原文件> translated.json -o <原名>.<语种>.docx
按 run_refs 找到本单元覆盖的所有原文本节点：把完整译文写入第一个节点，其余节点文本置空（XML 标签与属性完全保留，仅清空文字，不破坏任何节点）。这种"合并 run"机制保证译文不会被拆到多个 <w:t> 里造成断裂。最后用原压缩包结构重新打包。
4. 校验
python scripts/office_translate.py verify <输出文件>
检查压缩包完整、所有 XML 部件格式良好。
翻译准则（核心，务必遵守）
- 先通读该单元附带的
context（所在段落/文本框/单元格的整段文本），理解含义与语境。 - 再重写：用目标语言以母语者口吻自然表达，禁止逐词翻译、禁止中式英语（Chinglish）。
- 保持原意、语气、正式程度一致；不增删信息。
- 数字、日期、度量、货币、专有名词、品牌名、产品名、URL、代码、非语言符号保持不变。
- 绝不翻译、增删、臆造任何标记 / 占位符 / XML。单元里只会出现纯文本，但若遇到类似标记也保持原样。
- 结构性标点与分隔符必须保留：原文末尾或中间的分隔符（如标题分隔符
·、|、/、冒号、：等）是排版结构的一部分，逐单元重写时必须原样带在译文里，绝不能当作"多余标点"丢掉。典型反例：标签#房态·译完不能变成Room Status，而应是Room Status ·。 - 若原文已属目标语言或无需改动，原样返回。
关键约束
- 绝不允许破坏或翻译 XML 节点（如
<w:t>、<a:t>）。工具只替换文本节点的.text，标签与属性由解析器原样保留。 - 相邻 run 按样式分组合并：同一段落/单元格内、格式完全相同（
w:rPr一致）的相邻文本节点才合并成一个单元（run_refs），格式不同的 run 各自独立（保留其样式）；回填时本组的整句译文写入首个 run、同组其余 run 清空——这是为避免中英文被拆断且保留段落内样式，不是破坏结构（节点与样式都保留）。 - 修订删除痕迹（
w:del内）与域代码（instrText）不翻译。 - 仅数字/标点/空白的单元自动跳过，不翻译。
- 不重新发明排版：不要用"另存为纯文本再排版"的方式，必须走 OpenXML 解压→替换→重打包。
示例
用户上传 report.docx（中文），要翻译成英文：
# 1. 提取
python scripts/office_translate.py extract report.docx -o report.units.json
# 2. 切批（只取含中文的单元）
python scripts/office_translate.py split report.units.json --size 80 --out-dir batches --cjk-only
# 3. 智能体逐批翻译：读 batches/batch_000.json …，写 batches/batch_000.en.json …
# 4. 汇总回 translated.json
python scripts/office_translate.py collect report.units.json --batches batches -o report.translated.json
# 5. 回填重打包 + 校验
python scripts/office_translate.py apply report.docx report.translated.json -o report.en.docx
python scripts/office_translate.py verify report.en.docx
最终 report.en.docx 与原文排版、样式、图片完全一致，仅文字被替换为英文。
