用途
doc-i18n 是一个双语文档翻译技能，用于在基于路径的 i18n 项目中翻译、对比和同步中文与英文 Markdown 文档。其目标是确保结构对齐、内容一致性，并遵循项目特定的约定。
主要能力
- 将文档文件从一种语言翻译为另一种语言
- 对比两个语言版本，发现内容漂移或缺失章节
- 检查整个文档树的翻译覆盖率
- 翻译后修复标题 ID、内部链接或容器语法
- 从现有源文件创建新的翻译文件
使用方式
该技能按三个阶段执行工作流。
阶段一：分析
在做出任何更改之前，先分析任务：
- 识别源文件和目标文件，确定翻译方向：
- 英文到中文：docs/pages/{path}.md 到 docs/pages/zh/{path}.md
- 中文到英文：docs/pages/zh/{path}.md 到 docs/pages/{path}.md
- 读取两个文件（源文件和目标文件）。如果目标文件不存在，则需创建新文件。
- 生成差异报告，列出：
- 源文件中存在但目标文件中缺失或未翻译的标题
- 包含未翻译内容的段落或章节（例如英文文件中出现中文文本）
- 结构差异（多余或缺失的章节、内容顺序变化）
- 不同的代码块或示例
- 内部链接路径问题
- 标题 ID 不匹配
- 在继续之前向用户展示报告。如果是完整翻译任务，则在报告后直接继续。
阶段二：翻译
按照以下规则应用翻译：
内容规则
- 翻译正文，保留代码。翻译所有自然语言（段落、提示、引用块、列表项、标题）。保持代码块、行内代码、文件路径、CLI 命令、组件名称和 API 标识符不变。
- 翻译代码注释。代码块内的注释应翻译为目标语言。
- 精确保留 Markdown 结构。保持相同的标题层级、列表嵌套、引用块深度、容器语法和空行模式。
- Frontmatter。仅翻译 title 字段。保持所有其他 frontmatter 字段（categories、tags、layout 等）完全一致。
- 语气。中文使用简洁的技术文档风格；英文使用清晰、直接的技术英语。
容器语法
容器指令必须恰好使用 3 个冒号：
::: tip Content here. :::
::: warning Content here. :::
::: details Title Content here. :::
切勿使用 4 个或 5 个冒号。当项目约定不同时，阅读 references/conventions.md 获取项目特定的覆盖规则。
标题 ID 规则
- 所有带显式 ID（{#slug}）的标题在两种语言版本中都必须使用英文 slug，以保证跨语言锚点一致性。
- 英文文件：标题自动生成英文 slug，因此显式 ID 是可选的：
Getting Started
- 中文文件：标题必须包含显式英文 ID：
起步 {#getting-started}
- Slug 格式：小写，空格用连字符，去除所有格，例如：
- Get User's Valaxy Config → {#get-users-valaxy-config}
- Previous/Next Post → {#previous-next-post}
- Table of Contents → {#table-of-contents}
链接规则
- 内部文档链接必须使用正确的路径前缀：
- 英文文档（docs/pages/{path}.md）：链接不带前缀，例如 /guide/getting-started
- 中文文档（docs/pages/zh/{path}.md）：链接带 /zh/ 前缀，例如 /zh/guide/getting-started
- 锚点链接：始终使用英文 slug，例如 全局状态管理
- 外部链接：保持不变
代码块标签
保留代码块中的文件路径标签：
// code here
阶段三：验证
翻译完成后运行验证：
- 标题数量检查：两个文件在每个层级上应具有相同数量的标题
- 标题 ID 对齐：中文文件中的所有 {#id} slug 必须与英文文件中自动生成的 slug 匹配
- 链接检查：验证内部链接使用正确的路径前缀
- 容器语法检查：验证所有容器使用 3 个冒号
- 无混合语言：验证目标文件不包含未翻译的源语言文本（代码块和专有名词除外）
- Frontmatter 检查：验证 frontmatter 结构匹配（仅 title 不同）
- 向用户报告任何剩余问题
翻译覆盖率检查
当被要求检查整个文档的翻译覆盖率时：
- 列出 docs/pages/ 下的所有 .md 文件（排除 docs/pages/zh/）
- 对每个文件，检查 docs/pages/zh/ 下是否存在对应文件
- 报告：
- ✅ 两个版本都存在的文件
- ❌ 缺失中文翻译的文件
- 大小差异显著的文件（差异超过 50% 可能表示翻译不完整）
参考文件
- references/conventions.md — 项目特定的格式约定和覆盖规则。首次在任何项目上工作时阅读此文件，以了解项目特定规则。
适用场景
- 基于路径的 i18n 文档项目（如 Valaxy）的中英文翻译与同步
- 文档翻译覆盖率审计
- 翻译后的结构、链接、标题 ID 一致性修复
限制
- 该技能面向基于路径的 i18n 项目，路径约定为 docs/pages/ 与 docs/pages/zh/
- 具体项目约定可能不同，需参考 references/conventions.md
- 关于收费、价格、平台支持等信息暂未提供