docs-translate

name	docs-translate
description	Translate documents in place while preserving original copy. Use when user provides document path/name and asks to translate, convert language, localize, or sync suffixed translated documents back to original documents.

Docs Translate

触发

用户传入文档路径或文档名，要求翻译/转换语言/本地化文档，或要求根据语言后缀版本同步原文档。

默认行为

• 无语言后缀：用户给 guide.md / GUIDE.md 这类原文档时，将原文档翻译成目标语言；未指定目标语言时转为英文。
• 有语言后缀且无额外说明：用户给 guide_cn.md / GUIDE_CN.md 这类后缀版本时，将无后缀原文档更新到与该后缀版本语义一致。
• 语言后缀：放在扩展名前，格式为 [原名]_[语言代码].[扩展名]；语言代码大小写只由原名大小写决定，不能自行混用。
• 相同语言：翻译模式下，目标语言与原语言一致时，提示无需转换并停止。
• 原文纠正：默认跳过；只有用户提到“纠正/润色/改进表达/歧义”等才分析，翻译和同步都支持；同步场景优先分析后缀版本带来的可纠正点，最多列 15 条，询问确认后才修改原文。
• 内容和结构一致：同步/翻译时必须同时检查内容和结构；删除的要删除，增加的要增加，变更的要变更；不准只检查标题/列表等结构。
• 保留结构：保留标题层级、列表、表格、代码块、链接、Front Matter、占位符、变量名。
• 不翻译内容：代码、命令、路径、URL、配置键、API 名、品牌/产品专名，除非用户明确要求。
• 备份就是cp,不要浪费时间write

工作流

1. 定位文档

   • 用户给路径：直接使用。
   • 用户给名字：在当前仓库搜索同名或近似匹配文件；多结果时询问选择。

2. 识别模式

   • 无语言后缀：进入翻译模式。
   • 有语言后缀且用户无额外说明：进入同步原文模式。
   • 有语言后缀且用户明确要求翻译/改语言：按用户说明执行。

3. 翻译模式

   • 读取无后缀原文档。
   • 判断原语言；若目标语言与原语言一致，提示无需转换并停止。
   • 后缀代码大小写必须按“原名主体”决定，见「语言代码大小写规则」。
   • 若用户要求纠正，先执行「原文纠正建议」；用户确认后才修改原文，再继续翻译。
   • 复制原文档到 [原名]_[原语言代码].[扩展名]；若已存在，停止并询问，避免覆盖。
   • 将原文档翻译为目标语言，并写回原路径。
   • 逐段对照原文和译文，确认正文内容完整翻译，不遗漏段落、句子、表格单元格。
   • 确保翻译后文档与原文档内容和结构完全一致；删除、增加、变更必须逐项对应。

4. 同步原文模式

   • 从后缀文件名解析原文档路径：guide_cn.md → guide.md；GUIDE_CN.md → GUIDE.md。
   • 后缀代码大小写必须按“原名主体”校验：guide_CN.md、GUIDE_cn.md 都是不匹配命名，应提示用户改名或确认。
   • 读取后缀版本和原文档。
   • 对比两份文件时必须使用 git diff --no-index 原文档 后缀版本，用差异定位需要同步的内容。
   • 必须阅读 diff 中每个新增、删除、修改块；不能只看结构变化。
   • 若用户要求纠正，先执行「原文纠正建议」；同步场景必须重点检查后缀版本中的表达不清、歧义、术语不一致和可读性问题。
   • 以后缀版本为准，把原文档更新到语义一致；保持原文档目标语言和格式。
   • 用户确认纠正序号后，将纠正结果一并同步到原文档；未确认的纠正不得写入。
   • 确保原文档与后缀版本内容和结构完全一致；删除、增加、变更必须逐项同步。
   • 不创建新语言备份；这是同步更新，不是翻译备份。

5. 读取内容

   • 文本文件用 read。
   • PDF/DOCX/PPTX/XLSX/图片等非纯文本，先使用 liteparse 技能抽取内容。

6. 验证

   • 重新读取被写入文件，确认存在且非空。
   • 再次逐段对照源文档/后缀版本和被写入文件，确认内容完整、语义一致、结构一致。
   • 对 Markdown/Nix/JSON/YAML 等可校验格式，运行对应格式/语法检查；无检查器时至少确认内容和结构完全一致。

原文纠正建议

• 默认不做纠正，不主动改写原文；用户明确提到纠正/润色/歧义/表达改进时才执行。
• 翻译模式：翻译前通读原文，找表达不清、表达有歧义、语序别扭、术语不一致、可读性可改进之处；最多 15 条。
• 同步模式：这是纠正最重要的场景；必须结合 git diff --no-index 和后缀版本全文，优先找后缀版本新增/修改内容里的表达不清、歧义、术语不一致、可读性问题；最多 15 条。
• 用表格列出：序号、位置、来源文件、原文、问题、建议改法、理由；不直接修改文件。
• 表格后询问用户要应用哪些序号；用户确认后才先更新原文，再继续翻译或同步。

语言代码大小写规则

• 先取原名主体：去掉目录和最后扩展名；例如 docs/GUIDE.md 的原名主体是 GUIDE，docs/api.v1.md 的原名主体是 api.v1。
• 原名主体全部是大写字母/数字/分隔符时，语言代码必须全大写：GUIDE.md → GUIDE_CN.md，API-V1.md → API-V1_EN.md。
• 其他任何情况，语言代码必须全小写：guide.md → guide_cn.md，Guide.md → Guide_cn.md，api.v1.md → api.v1_en.md。
• 判断“全部大写”只看原名主体中的字母；没有小写字母才算全大写。
• 同步模式下，后缀文件也必须遵守同一规则；不匹配时停止并提示命名不一致。

翻译规则

• 忠实优先，润色次之。
• 标题短句可自然化，但不得改变含义。
• 技术文档术语前后一致。
• 保留 Markdown 链接目标，只翻译链接文本。
• 保留代码块原样；代码块外行内代码也原样保留。
• Front Matter 只翻译可见文案字段，保留键名和结构。

文件命名示例

• GUIDE.md 中文转英文：原名主体 GUIDE 全大写，备份 GUIDE_CN.md，GUIDE.md 写入英文。
• guide.md 中文转英文：原名主体 guide 非全大写，备份 guide_cn.md，guide.md 写入英文。
• Guide.md 中文转英文：原名主体 Guide 非全大写，备份 Guide_cn.md，Guide.md 写入英文。
• docs/spec.yaml 英文转日文：原名主体 spec 非全大写，备份 docs/spec_en.yaml，docs/spec.yaml 写入日文。
• guide_cn.md 且无额外说明：使用 git diff --no-index guide.md guide_cn.md 对比，更新 guide.md 到同等语义。
• GUIDE_CN.md 且无额外说明：使用 git diff --no-index GUIDE.md GUIDE_CN.md 对比，更新 GUIDE.md 到同等语义。

特别习惯

• 不论中英文,全部使用英文标点符号
• 纠正/润色时,常见表达不应该翻译为中文,例如:bug不应该翻译成错误

失败处理

• 找不到文档：说明搜索范围和匹配结果，询问准确路径。
• 多个候选：列出路径，等待用户选择。
• 备份名冲突：停止，不覆盖。
• 二进制格式无法安全写回：先说明限制，建议输出为 Markdown 或让用户确认目标格式。