desirecore/market
2
0
Fork 0
mirror of https://git.openapi.site/https://github.com/desirecore/market.git synced 2026-06-06 05:50:41 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
954891f9c29fe735e3038634ef379fe6c39b9f00
market/docs/I18N.md
Yige 1f7c8b9673 feat: skills i18n 改造（schemaVersion 1.1，零向后兼容） (#1) 
* feat: skills i18n 改造 — schemaVersion 1.1，零向后兼容

把 21 个 skills + 1 个 agent + manifest/categories 全量迁移到 schemaVersion 1.1
的 i18n 结构，配套 CI AI 翻译流水线（GitHub Models）与本地工具链。

## 关键变更

### 数据结构（破坏性，schemaVersion 1.0 → 1.1）
- SKILL.md: 顶层 name 改为 ASCII slug（== 目录名，符合 agentskills.io 规范）；
  中文显示名/short_desc/description 全部迁入 metadata.i18n.<locale>
- agents/<id>/agent.json: shortDesc/fullDesc/tags/persona.{role,traits} 迁入
  i18n.<locale>；changelog[].changes 改为 { <locale>: string[] } 对象
- categories.json: 每个分类的 label/description 迁入 i18n.<locale>，顶层只剩
  color/icon
- manifest.json: 加 supportedLocales / defaultLocale；顶层 description 迁入
  i18n.<locale>

### Body 文件结构
- 根 SKILL.md = frontmatter + default_locale (en-US) body
- SKILL.<locale>.md = 各 locale 的 markdown body（首行 <!-- locale: xx --> 自校验）

### 工具链（scripts/i18n/）
- glossary.json: zh→en 术语表 + do_not_translate 白名单
- schema/skill-frontmatter.schema.json: i18n frontmatter JSON Schema
- validate-i18n.py: 8 条校验规则（name 合规 / locale 完整性 / hash 一致性等）
- translate.py: GitHub Models / Anthropic 双 backend，sha256 增量翻译
- migrate.py: 一次性迁移脚本（旧格式 → i18n 结构）

### CI（.github/workflows/）
- i18n-validate.yml: PR 触发跑 validate + translate --check
- i18n-translate.yml: PR 触发用 GitHub Models（默认 openai/gpt-5-mini）翻译缺失
  locale，自动追加 commit；可切到 ANTHROPIC_API_KEY 走 Claude

### 文档
- docs/I18N.md: 作者贡献指南（schema 说明 / 提交流程 / 常见问题）
- README.md: 加多语言段落

## 验证

- uv run scripts/i18n/validate-i18n.py: OK，49 文件 0 错误
- uv run scripts/i18n/translate.py --check: 0 stale locale
- 21 skills 标题数 zh-CN == en-US 严格对齐（最大 66=66）
- skills-ref 规范校验：全部通过（顶层 name ASCII slug + description 单字段）

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(i18n): 修复 PR #1 review 反馈的 6 项问题

- schema: translated_by 正则放宽为 ^(human|ai:[A-Za-z0-9._:/-]+)$，接受
  'ai:github:openai/gpt-5-mini' 这类 backend:model 形式（CI 翻译输出格式）
- README + docs/I18N.md: 修正"CI 用 Claude API"误导描述，正确说明默认是
  GitHub Models（openai/gpt-5-mini）+ GITHUB_TOKEN，可选切到 Anthropic
- skills/minimax-tts/SKILL.md & SKILL.zh-CN.md: 删除多余的 ``` 闭合，避免
  Markdown 后续渲染错乱
- skills/docx/SKILL.md: 翻译时丢失的 • Unicode escape 示例已恢复，
  与 zh-CN 版本对齐

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-05 00:26:33 +08:00

176 lines
8.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Skills 多语言（i18n）作者指南
DesireCore 市场支持多语言展示与多语言 SKILL.md 正文。本指南面向 skill 作者与 maintainer，说明如何编写、提交、维护多语言 skill。
## 总则
- **作者只需要写一种语言**（推荐写中文 `zh-CN`）。CI 会自动调模型翻译为其余 `manifest.json#supportedLocales` 中声明的语言。**默认 backend 是 [GitHub Models](https://docs.github.com/en/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
```yaml
---
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`](../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](https://docs.github.com/en/github-models) 调模型。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](https://github.com/marketplace?type=models) 的 `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 提示「目标语已脱钩，请确认」，由你手工同步。
---
## 本地工具
```bash
# 校验 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 最佳实践](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) 里认可的写法。各 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](https://agentskills.io/specification)
- 最佳实践：[Anthropic Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/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`
Reference in New Issue View Git Blame Copy Permalink