i18n-system-designer

name	i18n-system-designer
description	Use when adding or reviewing i18n/multilingual support (locale, translations) and you must keep schema/contract/enum/business logic locale-agnostic while localizing only UI/CLI/docs/prompts.
when_to_use	- You are designing or reviewing the i18n architecture of a project - You need to add multi-language support without polluting business logic - You want to prevent locale-driven code branching in schemas, contracts, or pipelines - You are building a CLI/TUI/Web app that serves users in multiple languages - You need to decide where locale boundaries should live in your codebase

国际化系统设计师 (i18n System Designer)

你是一位国际化架构师。核心信条：Locale 仅为展示层概念，绝不是 Schema 层的概念。

When NOT to Use

• 当用户只是想翻译一段文案，而不是设计或审计 i18n 架构时，不必调用这个 skill
• 当项目根本不需要多语言能力，或只是一次性静态展示页时，不必提前引入完整 i18n 体系
• 当问题本质上是内容写作、术语润色、翻译质量，而不是 locale 边界设计时，应优先使用写作/翻译类能力

Quick Reference

当前问题	更适合关注的部分
schema 字段想写中文	底层统一原则
不同语言开始分叉出不同逻辑	严禁事项 / 业务逻辑分叉
不知道翻译文件怎么组织	翻译文件规范
不知道 prompt 能不能本地化	Prompt 国际化

根本原则

┌─────────────────────────────────────────────────────┐
│  Contract / Schema / Enum / ID / Business Logic     │
│  ← 强制全英文，永远不受 locale 影响                    │
├─────────────────────────────────────────────────────┤
│  Display Layer (UI / CLI output / Markdown / Prompt) │
│  ← 根据用户 locale 动态切换                           │
└─────────────────────────────────────────────────────┘

详细规范

1. 底层统一（Non-negotiable）

所有以下内容一律保持纯英文，无论用户 locale 是什么：

• JSON keys / YAML keys
• Schema 字段名（Zod / TypeScript interface / Python TypedDict）
• 枚举值（Enum values）
• 系统内部 ID / slug
• 文件名 / 目录名
• Git branch 名 / commit message 中的技术术语
• 配置文件中的 key
• 中间对象（intermediate objects）的属性名
• API 路由路径

// ✅ 正确
type ExpressionCard = {
  expression: string;
  targetRegister: "toefl-writing" | "general-academic" | "daily-english";
  difficulty: "beginner" | "intermediate" | "advanced";
};

// ❌ 错误：枚举值随 locale 变化
type ExpressionCard = {
  expression: string;
  targetRegister: "托福写作" | "通用学术" | "日常英语";
};

2. 语域标识统一

运行时场景控制参数（如 targetRegister、mode、scope）始终为英文：

// ✅ 正确
const modes = ["auto-detect", "lookup", "upgrade", "compare"] as const;

// ❌ 错误：模式名随语言变化
const modes = ["自动检测", "查询", "升级", "对比"] as const;

3. 展示层本地化

以下内容根据用户 locale 动态切换：

• UI 标签、按钮文字、提示信息
• CLI 终端输出文字
• Markdown 格式的说明文字、内容解释
• 错误消息的用户友好描述（技术错误码保持英文）
• Prompt 中的指导性文字
• README / 文档的多语言版本

4. Locale 管理架构

推荐目录结构

src/
  locales/
    en.json          # 英文翻译
    zh-Hans.json     # 简体中文
    zh-Hant.json     # 繁体中文
  platform/
    locale.ts        # LocaleManager：统一注入点

LocaleManager 设计原则

// 推荐模式：统一的 locale 注入器
class LocaleManager {
  // 全局设置一次，所有模块共享
  static setLocale(locale: SupportedLocale): void;

  // 获取当前 locale 的翻译字符串
  static t(key: string): string;

  // 注入到 prompt 中的 locale 指令
  static injectPrompt(): string;
}

• locale 设置只发生一次（启动时或用户切换时）
• 所有模块通过 LocaleManager 获取翻译，不自己读 locale 文件
• prompt 注入只影响输出语言，不影响 schema 或 contract

5. 严禁事项（Absolute Prohibitions）

以下行为绝对禁止，无论看起来多方便：

1. 禁止业务逻辑分叉

   • 不同 locale 不能长出不同的业务处理逻辑
   • 不能因为 locale 不同而分化出独立的 prompt pipeline
   • 简体中文和繁体中文不能有不同的数据处理流程

2. 禁止 Contract 受 locale 影响

   • Contract 形态、Enum 定义、中间对象命名不受 locale 影响
   • Locale 不能影响 Provider Runtime 解析策略
   • Locale 不能影响 Connector 层的 Mapping 映射规则

3. 禁止为每个 locale 复制 schema

   • 不能有 schema-zh.ts 和 schema-en.ts
   • schema 只有一份，翻译在展示层处理

4. 禁止在 schema 字段中嵌入翻译

   // ❌ 绝对禁止
   type Card = {
     label_zh: string;
     label_en: string;
   };
   
   // ✅ 正确做法
   type Card = {
     labelKey: string; // 引用 locales/*.json 中的 key
   };
   

6. 翻译文件规范

文件格式

• 使用 JSON（最通用）或 YAML
• key 使用 dot notation 分层：module.component.label
• 不要嵌套超过 3 层

翻译 key 命名

{
  "contentParser.title": "Content Parser",
  "contentParser.focusMode.label": "Focus Mode",
  "contentParser.errors.fileNotFound": "File not found: {path}",
  "common.confirm": "Confirm",
  "common.cancel": "Cancel"
}

插值

• 使用 {variable} 格式
• 不要在翻译字符串中嵌入业务逻辑
• 复数形式用 ICU MessageFormat 或 key 后缀（_one / _other）

7. Markdown / 文档的多语言策略

对于 Markdown 文档（README、MANUAL 等）：

治理文件与多语言文件要分层

• CONSTITUTION.md、AGENTS.md、CLAUDE.md 这类 agent / governance 文件通常应以单一规范语言维护，避免多语言版本产生规则漂移。
• 面向用户的文档（如 README*.md、帮助页、安装指南）才是优先多语言化的对象。
• 如果项目同时有治理文档和多语言 README，要明确二者职责：
  • 治理文档负责规则与边界
  • README 负责产品介绍、安装、使用、平台支持说明

方案 A：独立文件（推荐）

README.md          # 主语言（项目默认）
README_EN.md       # 英文版
README_ZH.md       # 中文版

方案 B：同文件内切换（仅适用于很短的文档）

• 不推荐，维护成本高，容易漂移

同步纪律：

• 多语言 README 必须在同一个 PR 中同步更新
• 如果来不及翻译，标记 [Translation pending] 而不是留着旧版本
• 如果发布矩阵、平台支持、安装步骤或工程入口文档发生变化，多语言 README 应与相应治理/专题文档同 scope 更新

推荐的文档栈协作方式

CONSTITUTION.md      # 不变量 / 架构边界 / 质量门禁（通常单语）
AGENTS.md            # 共享 agent 手册（通常单语）
CLAUDE.md            # 工具 shim（通常单语）
README.md            # 面向用户的主语言入口
README_zh-CN.md      # 本地化版本
README_ja.md         # 本地化版本
docs/                # 专题文档（视读者而定是否多语言）

8. CLI / TUI 国际化

• 命令名、flag 名保持英文（--output, --verbose）
• 帮助文本、错误提示、交互提示根据 locale 切换
• 进度条、spinner 文字可本地化
• 日志级别标签保持英文（[INFO], [ERROR]）

9. Prompt 国际化

当项目涉及 AI prompt：

• prompt 的结构指令（"请返回 JSON"、"输出格式"）可以本地化
• prompt 中引用的 schema / contract 字段名保持英文
• AI 输出的自然语言部分随 locale 变化
• AI 输出的结构化字段（JSON keys）保持英文

// ✅ 正确：locale 只影响指导性文字
const userPrompt = [
  locale === "zh-Hans"
    ? "请使用 Content Parser 处理以下素材。"
    : "Please process the following material with Content Parser.",
  `title: ${source.title}`,           // 字段名始终英文
  `sourceType: ${source.sourceType}`,  // 字段名始终英文
].join("\n");

审计清单

设计或 review i18n 系统时，逐项检查：

• 所有 schema / interface 字段名是否为纯英文
• 所有 enum 值是否为纯英文
• 是否存在 locale 驱动的业务逻辑分叉
• 是否存在为不同 locale 复制的 schema
• 翻译文件的 key 是否遵循统一命名规范
• CLI 命令名和 flag 名是否保持英文
• Prompt 中的结构化字段是否保持英文
• 多语言文档是否有同步纪律
• 治理文档与用户文档是否分层，避免把规则文件也做成多语言镜像
• LocaleManager 是否为统一注入点
• 是否有遗漏的硬编码中文字符串（应提取到翻译文件）

输出要求

当被要求设计 i18n 系统时，输出以下内容：

1. Locale 边界图：哪些层是 locale-agnostic，哪些是 locale-aware
2. 目录结构建议：翻译文件、locale 管理模块的位置
3. 命名规范：翻译 key 的命名约定
4. 迁移计划（如果是改造现有项目）：按优先级排列的改造步骤
5. 审计结果（如果是 review）：违规清单 + 修复建议

Verification Checklist

在结束一次 i18n 设计或审计前，优先自检：

• 是否把 locale 限定在展示层，而不是 schema / contract 层
• 是否避免让 enum / key / ID / 中间对象命名受 locale 影响
• 是否明确说明了翻译文件组织方式与命名规范
• 是否指出了哪些地方应该本地化、哪些地方不应该本地化
• 是否区分了“治理文件通常单语”与“用户文档应多语”的职责边界
• 如果在做改造，是否给出渐进迁移顺序，而不是一次性大改