market/docs/I18N.md

Skills 多语言（i18n）作者指南

DesireCore 市场支持多语言展示与多语言 SKILL.md 正文。本指南面向 skill 作者与 maintainer，说明如何编写、提交、维护多语言 skill。

总则

• 作者只需要写一种语言（推荐写中文 zh-CN）。CI 会自动调模型翻译为其余 manifest.json#supportedLocales 中声明的语言。默认 backend 是 GitHub Models（openai/gpt-5-mini），使用 repo 内置 GITHUB_TOKEN，无需额外 secret；可选切到 Anthropic Claude（见下文 CI 流水线一节）。
• 目录名 == name 字段：spec 强制约束（agentskills.io）。目录名是 ASCII slug；显示名（中/英/其他）安放在 metadata.i18n.<locale>.name。
• 默认语言：en-US。Fallback 链：requested locale → source_locale → default_locale。市场仓库 schemaVersion 1.1+ 必填 metadata.i18n 块，无顶层 legacy 字段兜底。
• 禁止占位：不要直接编辑 metadata.i18n.<locale>.source_hash 与 translated_at，这些字段由 translate.py 维护。

---

文件结构

skills/<your-skill>/
├── SKILL.md                  # 顶层 frontmatter + 默认语言 (en-US) body
├── SKILL.zh-CN.md            # 中文 body（作者源语言）
├── SKILL.<locale>.md         # 其他语言 body（CI 生成）
├── references/               # 可选：扩展文档
└── scripts/                  # 可选：可执行脚本

只有 SKILL.md 有 frontmatter，其余 SKILL.<locale>.md 仅含 body，并在首行写 <!-- locale: <locale> -->。

---

Frontmatter Schema

---
name: your-skill                    # 必须 == 父目录名（ASCII slug）
description: >-                     # 单字段，Claude 检索用；建议含中英触发词
  Use this skill when the user wants to ... 用户提到 ...、...、...
license: MIT
version: 1.0.0
metadata:
  author: your-org
  updated_at: '2026-05-03'
  i18n:
    default_locale: en-US           # fallback 终点
    source_locale: zh-CN            # 你写的源语言
    locales: [zh-CN, en-US]         # 已提供的 locale
    zh-CN:
      name: 你的技能名
      short_desc: 一句话描述
      description: 较长的中文描述（可选）
      body: ./SKILL.zh-CN.md
      source_hash: sha256:xxxxxxxx  # CI 维护
      translated_by: human          # human 或 ai:<model-id>
    en-US:
      name: Your Skill Name
      short_desc: One-line description
      description: Longer English description
      body: ./SKILL.md              # 默认语言 = 根 SKILL.md
      source_hash: sha256:xxxxxxxx
      translated_by: ai:claude-sonnet-4-6
      translated_at: '2026-05-03'
market:
  icon: <svg>...</svg>
  category: productivity
  channel: latest
  maintainer:
    name: DesireCore Official
    verified: true
---

完整 JSON Schema：scripts/i18n/schema/skill-frontmatter.schema.json

---

提交流程

新建 skill（首次贡献）

1. 在 skills/<your-slug>/ 下新建目录与 SKILL.md。
2. 编写中文 frontmatter + 中文 body：
   • name: <your-slug>（ASCII）
   • metadata.i18n.{default_locale: en-US, source_locale: zh-CN, locales: [zh-CN]}
   • metadata.i18n.zh-CN.{name, short_desc, description}
   • metadata.i18n.zh-CN.body: ./SKILL.zh-CN.md
   • 中文正文写在 SKILL.zh-CN.md，首行 <!-- locale: zh-CN -->
   • 根 SKILL.md body 留作翻译占位符（CI 会替换）
3. 本地校验：uv run scripts/i18n/validate-i18n.py skills/<your-slug>
4. 开 PR。CI 会自动追加一个 commit，把 en-US 翻译填入根 SKILL.md 与 metadata.i18n.en-US。
5. 审 CI 翻译：检查英文术语、Markdown 结构。若需修改，编辑后把 metadata.i18n.en-US.translated_by 改为 human，CI 不会再覆盖。

CI 翻译流水线（GitHub Actions）

CI 用 GitHub Models inference API 调模型。Workflow .github/workflows/i18n-translate.yml：

• 触发：PR 改动 skills/**/SKILL.zh-CN.md 或 manifest.json/categories.json；或 workflow_dispatch 手动触发。
• 认证：用 repository 的 GITHUB_TOKEN（无需额外 secret），workflow 声明 permissions: models: read。
• 默认模型：openai/gpt-5-mini（catalog 中性价比款 GPT-5；想要旗舰精度切到 openai/gpt-5。GitHub Models 当前未上架 Anthropic Claude，仅 OpenAI / DeepSeek / Meta / xAI / Microsoft 系列）。
• 切换模型：repository → Settings → Variables → TRANSLATE_MODEL，取值参考 GitHub Models marketplace 的 publisher/model-name 格式。
• 切到 Anthropic Claude：在 repo 加 secret ANTHROPIC_API_KEY，再加 variable TRANSLATE_BACKEND=anthropic、TRANSLATE_MODEL=claude-sonnet-4-6。

提交回仓库的方式：desirecore-bot 在同 PR 追加 commit chore(i18n): auto-translate skills [skip ci]，并在 PR 留 review comment 提示人工核对。

修改已有 skill

1. 修改源语言 body（SKILL.zh-CN.md）或 metadata.i18n.zh-CN.{name,short_desc,description}。
2. 不要手动改 source_hash。
3. 开 PR。CI 检测 hash 变化，重新翻译目标 locale 并追加 commit。
4. 若某个 locale 的 translated_by: human，CI 会跳过该 locale 并在 PR 留 review 提示「目标语已脱钩，请确认」，由你手工同步。

---

本地工具

# 校验 i18n 状态
uv run scripts/i18n/validate-i18n.py
uv run scripts/i18n/validate-i18n.py skills/web-access

# 一次性把旧格式 SKILL.md 迁移到 i18n 格式（旧 skill 已迁完，新 skill 一般不需要）
uv run scripts/i18n/migrate.py --apply skills/<your-slug>

# 仅检查哪些 locale 缺翻译（不调 API）
uv run scripts/i18n/translate.py --check

# 本地翻译：默认走 GitHub Models（需 fine-grained PAT，启用 Models: Read 权限）
GITHUB_TOKEN=ghp_... uv run scripts/i18n/translate.py skills/<your-slug>

# 切到 Anthropic Claude（需 sk-ant-...）
TRANSLATE_BACKEND=anthropic ANTHROPIC_API_KEY=sk-ant-... \
  uv run scripts/i18n/translate.py skills/<your-slug>

# 选择特定模型（默认 GitHub: openai/gpt-5-mini；Anthropic: claude-sonnet-4-6）
TRANSLATE_MODEL=openai/gpt-5 GITHUB_TOKEN=... \
  uv run scripts/i18n/translate.py skills/<your-slug>

---

术语表

scripts/i18n/glossary.json 是翻译的事实来源。提交新 skill 时，如果引入了领域专有名词（例如 "审批流"、"工单"），请在 PR 中追加术语映射。

不要在术语表里加：

• 已经在 do_not_translate 列表里的品牌/技术词
• 译文与字面意义无差别的通用词

---

常见问题

Q：为什么顶层 description 还混着中英文？ 因为 Claude 只用单字段 description 在 100+ skills 中匹配 user query。混合触发词是 Anthropic 官方在 skill 最佳实践 里认可的写法。各 locale 的纯净版本走 metadata.i18n.<locale>.description，市场 UI 读这里。

Q：CI 翻译质量不达预期怎么办？

1. 在 glossary.json 里加更具体的术语映射。
2. 直接手工编辑目标 locale 的 body 与 frontmatter，并把 translated_by 改为 human，CI 不会再覆盖。
3. 若是普遍问题，到 repo Settings → Variables 改 TRANSLATE_MODEL（默认 openai/gpt-5-mini，可选 openai/gpt-5、openai/gpt-5-nano、openai/gpt-4.1、meta/llama-3.3-70b-instruct 等），或切到 TRANSLATE_BACKEND=anthropic 用 Claude。

Q：能否禁用某个 locale 的自动翻译？ 可以。在 manifest.json#supportedLocales 中删除该 locale；或在 skill 级别保留 metadata.i18n.locales 不含它（CI 不会主动新增）。

Q：references/ 里的文档需要翻译吗？ 当前不强制。未来扩展时使用 references/<file>.<locale>.md 兄弟文件命名，与 SKILL body 一致。

---

相关文件

• 规范：agentskills.io/specification
• 最佳实践：Anthropic Skill authoring best practices
• 术语表：scripts/i18n/glossary.json
• JSON Schema：scripts/i18n/schema/skill-frontmatter.schema.json
• 校验：scripts/i18n/validate-i18n.py
• 翻译：scripts/i18n/translate.py
• 迁移：scripts/i18n/migrate.py
• CI workflows：.github/workflows/i18n-{validate,translate}.yml