translate

name	translate
description	扫描 raw/ 中的英文素材并翻译为中文。Use when the user wants to translate raw materials to Chinese or check for untranslated documents.
argument-hint	[文件路径, --scan, or --all]

/translate — 翻译素材

扫描 raw/ 中的素材，将英文内容翻译为中文。已是中文的素材自动跳过。

---

模式一：翻译指定文件（提供了文件路径）

1. 读取指定文件内容
2. 语言检测：检查正文部分（不含 frontmatter 和代码块）是否已经是中文
   • 判断标准：正文中中文字符占非空白、非 ASCII 标点字符的比例 > 50% 即视为中文
   • 如果已是中文，告知用户"该文件已是中文，跳过翻译"并结束
3. 翻译正文内容，规则如下：
   • 翻译范围：仅翻译正文文本，不修改文件名
   • 保持不变的内容：
     • YAML frontmatter 的字段名和结构（title 字段的值需翻译）
     • description 字段的值需翻译
     • 代码块（``` 包裹的内容）
     • URL 链接地址
     • API 端点、请求头名称、HTTP 方法
     • 命令行示例
     • 技术标识符（函数名、变量名、参数名、类型名）
     • 图片引用路径（![[...]]）
   • 翻译风格：
     • 技术术语首次出现时保留英文原文，如"运行框架（harness）"
     • 核心概念在表格中采用"中文（English）"格式
     • 行文流畅自然，不是机械的逐句直译
     • 使用中文标点符号
4. 将翻译后的内容覆盖写入原文件（原地替换，不创建新文件）
5. 报告翻译完成

---

模式二：扫描翻译（--scan 或无参数）

批量扫描并翻译所有未翻译的素材。

1. 递归扫描 raw/ 所有子目录，找出所有 .md 文件（排除 _registry.md、_index.md、.gitkeep）
2. 对每个文件进行语言检测（同模式一的判断标准）
3. 列出检测结果：
   • ✓ 已是中文（跳过）：N 个
   • ✗ 需要翻译：N 个（列出文件路径）
4. 逐个翻译需要翻译的文件（遵循模式一的翻译规则）
5. 翻译完成后报告：共扫描 X 个文件，翻译 Y 个，跳过 Z 个

---

模式三：全量强制翻译（--all）

忽略语言检测，对所有文件重新执行翻译。用于修正之前翻译质量不佳的情况。

---

翻译质量要求

• 准确性：技术内容必须准确，不得曲解原文含义
• 可读性：译文应符合中文技术文档的阅读习惯，避免翻译腔
• 一致性：同一术语在所有文件中使用统一的翻译，参考 wiki/glossary/ 已有译法
• 完整性：不遗漏段落或章节，不添加原文没有的内容

注意事项

• 不修改文件名，只翻译文件内正文内容
• 翻译后覆盖原文件，不创建新的翻译副本
• 如果文件内中英混杂（如中文正文中嵌入英文代码示例），只翻译中文不足的文本部分
• source 和 author 等元数据字段保持原样不翻译