重要提示： 每个语言环境必须保持与 en/ 完全相同的文件结构和 JSON 键顺序。

国际化架构

本项目有两个独立的国际化系统，它们共享相同的 12 个语言环境配置：

1. UI 翻译系统 (next-intl)

• 用途： 翻译静态 UI 字符串（按钮、标签、页面内容等）
• 位置： translations/{locale}/*.json
• 使用方式： 通过 useTranslations() 钩子或 getTranslations() 服务器函数
• 管理方式： 此技能的同步和翻译命令

2. 清单翻译系统

• 用途： 翻译清单数据（IDE、CLI、模型、提供商等）
• 位置： manifests/**/*.json（在每个清单文件的 translations 字段中）
• 使用方式： 通过 localizeManifestItem() 和 localizeManifestItems() 函数
• 管理方式： 手动编辑清单文件或使用清单自动化工具

此技能仅管理 UI 翻译系统。 对于清单翻译，请直接编辑清单 JSON 文件或使用清单自动化技能。

启用的语言环境

src/i18n/config.ts 中当前启用的语言环境：

• en - 英语（源语言）
• de - Deutsch（德语）
• es - Español（西班牙语）
• fr - Français（法语）
• id - Bahasa Indonesia（印度尼西亚语）
• ja - 日本語（日语）
• ko - 한국어（韩语）
• pt - Português（葡萄牙语）
• ru - Русский（俄语）
• tr - Türkçe（土耳其语）
• zh-Hans - 简体中文（简体中文）
• zh-Hant - 繁體中文（繁体中文）

所有 12 个语言环境均已完全启用，必须保持同步。

子命令

sync

将所有启用的语言环境目录与作为源语言的 en/ 目录同步。

功能：

• 扫描 translations/ 中所有在配置中启用的语言环境目录
• 将每个 JSON 文件的键与对应的英语文件进行比较
• 添加缺失的键，并使用英语文本作为占位符（需要翻译）
• 移除英语文件中不存在的额外键
• 保留 JSON 结构、键顺序和格式（2 空格缩进）
• 保持每个语言环境的 index.ts 文件结构

用法：

当需要同步语言文件时，在 Claude Code 中使用此命令：

Please run the i18n sync command

Claude Code 将执行：

node .claude/skills/i18n/scripts/sync.mjs

输出示例：

🔄 Syncing translation files with en/...

✓ Synced de/
  + Added 3 keys in components.json
  + Added 5 keys in pages/home.json
  - Removed 1 key in shared.json

✓ Synced zh-Hans/
  + Added 8 keys in pages/stacks.json

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Sync complete!
  Modified: 2 locales
  Added: 16 keys
  Removed: 1 key

使用时机：

• 向任何英语 JSON 文件添加新键后
• 从任何英语 JSON 文件中移除过时键后
• 向英语结构中添加新的 JSON 文件后
• 开始翻译工作之前（确保所有键都存在）
• 添加新语言环境时

translate <locale>

为 Claude Code 生成翻译任务，以翻译缺失的内容。

功能：

• 读取 en/ 和 <locale>/ 中的所有 JSON 文件
• 识别需要翻译的键（当前为英语或缺失）
• 输出带有指南的结构化翻译任务
• 为准确翻译提供上下文和说明

用法：

当需要翻译内容时，在 Claude Code 中使用此命令：

Please run the i18n translate command for ja

Claude Code 将执行：

node .claude/skills/i18n/scripts/translate.mjs ja

工作流程：

1. 脚本以 JSON 格式输出需要翻译的内容
2. Claude Code 读取指南并翻译内容
3. 您提供翻译后的 JSON
4. Claude Code 更新语言环境 JSON 文件

翻译指南（自动强制执行）：

✓ 保留品牌名称： AI Coding Stack、Claude Code 等。 ✓ 保持占位符完整： {count}、{name}、${variable} ✓ 不翻译 URL： https://example.com ✓ 不翻译文件路径： /path/to/file ✓ 在整个翻译过程中保持术语一致性 ✓ 保留引用语法： @:path.to.key 用于内部引用

输出示例：

🌐 Translation Assistant for ja

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📝 Translation Task
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Target Language: 日本語 (Japanese)
Entries to translate: 15

Files affected:
  - components.json: 5 entries
  - pages/home.json: 8 entries
  - shared.json: 2 entries

⚠ Translation Guidelines:
  1. Preserve brand names: "AI Coding Stack", "Claude Code"
  2. Keep placeholders intact: {count}, {name}, ${variable}
  3. Don't translate URLs and file paths
  4. Maintain consistent terminology
  5. Preserve reference syntax: @:path.to.key

Content to translate:

```json
{
  "components.languageSwitcher.english": "English",
  "pages.home.hero.title": "Welcome to AI Coding Stack",
  "shared.navigation.docs": "Documentation",
  ...
}



---

## 文件结构

.claude/skills/i18n/ ├── SKILL.md # 此文档 └── scripts/ ├── sync.mjs # 同步脚本 └── translate.mjs # 翻译助手脚本

## 技术细节

**语言：** Node.js (ES Modules)
**依赖项：** 仅使用内置 Node.js 模块 (`fs`, `path`)
**JSON 格式：** 2 空格缩进，末尾换行符
**编码：** UTF-8

### 翻译文件结构

每个语言环境包含：
1.  **JSON 文件：** 包含实际的消息数据
2.  **index.ts：** 导入并组装消息

```typescript
// translations/en/index.ts
import components from './components.json'
import articles from './pages/articles.json'
import comparison from './pages/comparison.json'
import curatedCollections from './pages/curated-collections.json'
import docs from './pages/docs.json'
import home from './pages/home.json'
import landscape from './pages/landscape.json'
import manifesto from './pages/manifesto.json'
import openSourceRank from './pages/open-source-rank.json'
import search from './pages/search.json'
import stacks from './pages/stacks.json'
import shared from './shared.json'

const messages = {
  shared,
  components,
  pages: {
    home,
    manifesto,
    docs,
    articles,
    curatedCollections,
    stacks,
    comparison,
    landscape,
    openSourceRank,
    search,
  },
}

export default messages

键的比较方式

脚本使用递归遍历来处理嵌套的 JSON 结构。使用点表示法比较键：

{
  "pages": {
    "home": {
      "hero": {
        "title": "Welcome"
      }
    }
  }
}

变为：pages.home.hero.title = "Welcome"

添加新语言

注意： 本项目目前支持 12 个语言环境。要添加新的语言环境（例如，意大利语 'it'）：

1. 将语言环境添加到 src/i18n/config.ts：

   export const locales = [ 'en', 'de', 'es', 'fr', 'id', 'ja', 'ko', 'pt', 'ru', 'tr', 'zh-Hans', 'zh-Hant', 'it' // 添加新语言环境 ] as const;

2. 更新语言环境名称：

   export const localeNames: Record<Locale, string> = { // ... 现有语言环境 it: 'Italiano', }

   export const localeToOgLocale: Record<Locale, string> = { // ... 现有语言环境 it: 'it_IT', }

3. 添加到 translate.mjs 的 LOCALE_NAMES（.claude/skills/i18n/scripts/translate.mjs）：

   const LOCALE_NAMES = { // ... 现有语言环境 it: 'Italiano (Italian)', }

4. 创建语言环境目录结构：

   mkdir -p translations/it/pages cp translations/en/index.ts translations/it/index.ts cp translations/en/.json translations/it/ cp translations/en/pages/.json translations/it/pages/

5. 运行 sync 以确保结构匹配：

   Please run the i18n sync command

6. 运行 translate 以生成翻译任务：

   Please run the i18n translate command for it

最佳实践

1. 始终在 translate 之前运行 sync，以确保所有键都存在
2. 先对英语文件进行更改，然后同步其他语言环境
3. 审查翻译以确保上下文准确性，尤其是技术术语
4. 使用 Git 跟踪更改并在提交前审查差异
5. 在所有语言中保持品牌名称一致
6. 在实际 UI 中测试翻译以验证格式和长度
7. 保持键顺序以便更轻松地审查差异
8. 对重复使用的内容使用引用语法 (@:path.to.key)

故障排除

问题： 脚本显示 "directory not found"

• 解决方案： 确保从项目根目录运行
• 检查 translations/ 目录是否存在

问题： 添加新内容后键不同步

• 解决方案： 运行 sync 命令以更新所有语言环境文件

问题： 翻译包含 {0} 而不是 {count} 之类的占位符

• 解决方案： 验证英语源是否使用命名占位符，重新翻译

问题： 翻译后的应用程序中某些文本显示为英语

• 解决方案： 运行 translate 以查找缺失的翻译，检查英语回退

问题： sync 后 index.ts 导入错误

• 解决方案： 同步脚本保留 index.ts 结构；手动检查导入是否与实际 JSON 文件匹配

与 next-intl 集成

此技能设计用于与项目的 next-intl 设置配合使用：

// src/i18n/request.ts
const rawMessages = (await import(`../../translations/${locale}/index.ts`)).default
const messages = resolveReferences(rawMessages)

JSON 文件通过每个语言环境的 index.ts 加载，resolveReferences 函数处理引用语法。

引用解析

本项目支持引用语法以重用翻译：

基本引用： @:path.to.key

{
  "shared": {
    "appName": "AI Coding Stack",
    "welcome": "Welcome to @:shared.appName"
  }
}
// 结果："Welcome to AI Coding Stack"

带修饰符的引用： @.modifier:path.to.key

支持的修饰符：

• @.upper:path - 转换为大写

• @.lower:path - 转换为小写

• @.capitalize:path - 首字母大写

  { "terms": { "documentation": "documentation", "title": "@.capitalize:terms.documentation Guide" } } // 结果："Documentation Guide"

重要提示：

• 引用在运行时由 src/i18n/lib-core.ts 解析
• 检测到循环引用将抛出错误
• 引用可以嵌套（引用中的引用）
• 翻译时保持引用语法完整

许可证

此技能是 AI Coding Stack 项目的一部分，遵循项目的 Apache 2.0 许可证。

每周安装次数

1

仓库

aicodingstack/a…stack.io

GitHub 星标数

28

首次出现

1 天前

安全审计

Gen Agent Trust HubPassSocketPassSnykPass

安装于

claude-code1