@qlover/create-app 0.7.15 → 0.8.0

package/dist/templates/react-app/docs/zh/i18n.md

@@ -1,152 +1,568 @@
-# 国际化系统
+# 国际化 (i18n)
 
-## 概述
+## 📋 目录
 
-国际化系统采用基于标识符别名的方案，结合 i18next 和 TypeScript 注释，实现了一个类型安全、易维护的国际化解决方案。主要特点：
+- [核心理念](#-核心理念) - 绝不硬编码，只用变量
+- [什么是 i18n Key](#-什么是-i18n-key) - 唯一标识符
+- [为什么使用 i18n Key](#-为什么使用-i18n-key) - 减少思考负担
+- [项目中的实现](#-项目中的实现) - Bootstrap 插件
+- [使用方式](#-使用方式) - 实战指南
+- [最佳实践](#-最佳实践) - 7 条核心实践
+- [常见问题](#-常见问题) - FAQ
 
-- **标识符别名**：使用常量而非字符串作为翻译键
-- **TypeScript 注释**：通过注释自动生成翻译资源
-- **类型安全**：完整的类型检查和自动补全
-- **路由集成**：支持 URL 路径中的语言参数
-- **自动生成**：自动从源码生成翻译文件
-- **开发友好**：完整的开发工具支持
+---
 
-## 核心概念
+## 🎯 核心理念
 
-### 1. 标识符别名
+> **🚨 重要原则：项目中所有需要显示的文字、词语、句子，都必须使用 i18n Key，绝不允许硬编码文本！**
 
-使用常量替代字符串键值，提供更好的类型安全和维护性：
+> **⭐ 核心优势：开发者不需要记住复杂的翻译字符串，只需要知道变量名，IDE 会提供自动补全！**
+
+### 核心概念
+
+```
+❌ 硬编码文本        ✅ i18n Key（变量）
+"登录"          →   BUTTON_LOGIN (不需要记住 'common:button.login')
+"欢迎回来"       →   MESSAGE_WELCOME (不需要记住 'common:message.welcome')
+"确定要删除吗？" →   CONFIRM_DELETE (不需要记住 'common:confirm.delete')
+```
+
+**每个文本都有唯一的标识符：**
 
 ```typescript
-// config/Identifier/common.ts
+// ❌ 错误：直接写文字或字符串
+<button>登录</button>
+<h1>欢迎回来</h1>
+<p>{t('common:confirm.delete')}</p>  // 也不要写字符串
+
+// ✅ 正确：使用 i18n Key 变量
+<button>{t(BUTTON_LOGIN)}</button>       // 只需记住变量名
+<h1>{t(MESSAGE_WELCOME)}</h1>            // IDE 会自动补全
+<p>{t(CONFIRM_DELETE)}</p>               // TypeScript 会检查拼写
+```
+
+---
+
+## 🔑 什么是 i18n Key
+
+i18n Key 是**每个文本的唯一标识符**，就像每个人都有身份证号一样。
+
+### 基本概念
+
+```typescript
+// i18n Key 定义（在 config/Identifier/ 目录下）
 
 /**
- * @description Theme switcher default theme label
- * @localZh 默认主题
- * @localEn Default Theme
+ * @description Login button text
+ * @localZh 登录
+ * @localEn Login
  */
-export const HEADER_THEME_DEFAULT = 'header.theme.default';
+export const BUTTON_LOGIN = 'common:button.login';
+//            ↑ 常量名                 ↑ 标识符字符串
+//            用于代码中引用          存储在翻译文件中的键名
 
 /**
- * @description Theme switcher dark theme label
- * @localZh 暗色主题
- * @localEn Dark Theme
+ * @description Welcome message
+ * @localZh 欢迎回来，{{name}}！
+ * @localEn Welcome back, {{name}}!
  */
-export const HEADER_THEME_DARK = 'header.theme.dark';
+export const MESSAGE_WELCOME = 'common:message.welcome';
 ```
 
-### 2. 自动生成配置
+**结构说明：**
+
+```
+'common:button.login'
+   ↑      ↑      ↑
+命名空间  分类   具体标识
+```
 
-在 `vite.config.ts` 中配置自动生成：
+### 命名规范
 
 ```typescript
-import ts2Locales from '@brain-toolkit/ts2locales/vite';
+// ✅ 好的命名：清晰、结构化
+export const BUTTON_LOGIN = 'common:button.login'; // 按钮文本
+export const BUTTON_SUBMIT = 'common:button.submit'; // 按钮文本
+export const MESSAGE_WELCOME = 'common:message.welcome'; // 消息文本
+export const CONFIRM_DELETE = 'common:confirm.delete'; // 确认对话框
+export const ERROR_NETWORK = 'common:error.network'; // 错误信息
+export const PAGE_HOME_TITLE = 'common:page.home.title'; // 页面标题
+
+// ❌ 不好的命名：模糊、无结构
+export const TEXT1 = 'login';
+export const MSG = 'welcome';
+export const DELETE_CONFIRM = 'delete_confirm';
+```
 
-export default defineConfig({
-  plugins: [
-    ts2Locales({
-      locales: ['en', 'zh'],
-      options: [
-        {
-          source: './config/Identifier/common.ts',
-          target: './public/locales/{{lng}}/common.json'
-        },
-        {
-          source: './config/Identifier/error.ts',
-          target: './public/locales/{{lng}}/common.json'
-        }
-      ]
-    })
-  ]
-});
+---
+
+## 🤔 为什么使用 i18n Key
+
+### 问题：硬编码文本的痛点
+
+```typescript
+// ❌ 传统方式：文本硬编码
+
+function LoginPage() {
+  return (
+    <div>
+      <h1>登录</h1>
+      <button>登录</button>
+      <p>欢迎回来！</p>
+      <span>忘记密码？</span>
+    </div>
+  );
+}
+
+// 😰 问题 1：国际化困难
+// 如果要支持英文，需要修改大量代码
+
+// 😰 问题 2：维护困难
+// 同样的文本可能在多个地方使用，修改时容易遗漏
+
+// 😰 问题 3：难以统一管理
+// 无法统计项目中有多少个文本，哪些需要翻译
+
+// 😰 问题 4：搜索困难
+// 想找到某个文本在哪里使用，只能全局搜索字符串
+```
+
+### 解决方案：使用 i18n Key
+
+```typescript
+// ✅ 使用 i18n Key
+
+import { useAppTranslation } from '@/uikit/hooks/useAppTranslation';
+import {
+  PAGE_LOGIN_TITLE,
+  BUTTON_LOGIN,
+  MESSAGE_WELCOME,
+  LINK_FORGOT_PASSWORD
+} from '@config/Identifier';
+
+function LoginPage() {
+  const { t } = useAppTranslation();
+
+  return (
+    <div>
+      <h1>{t(PAGE_LOGIN_TITLE)}</h1>
+      <button>{t(BUTTON_LOGIN)}</button>
+      <p>{t(MESSAGE_WELCOME)}</p>
+      <span>{t(LINK_FORGOT_PASSWORD)}</span>
+    </div>
+  );
+}
+
+// ✅ 优势 1：自动国际化
+// 根据用户语言自动显示对应文本
+
+// ✅ 优势 2：集中管理
+// 所有文本在 Identifier 文件中统一管理
+
+// ✅ 优势 3：易于维护
+// 修改文本只需修改一处
+
+// ✅ 优势 4：类型安全
+// TypeScript 会检查 Key 是否存在
+
+// ✅ 优势 5：减少思考 ⭐
+// 开发者只需要知道 BUTTON_LOGIN 是一个变量
+// 不需要记住 'common:button.login' 这个字符串
+// IDE 会提供自动补全，写错了会立即报错
+```
+
+### 对比总结
+
+| 特性         | 硬编码文本            | i18n Key                |
+| ------------ | --------------------- | ----------------------- |
+| **国际化**   | ❌ 困难（需要改代码） | ✅ 自动（切换语言即可） |
+| **维护性**   | ❌ 差（分散各处）     | ✅ 好（集中管理）       |
+| **重用性**   | ❌ 差（复制粘贴）     | ✅ 好（引用 Key）       |
+| **搜索性**   | ❌ 困难（字符串搜索） | ✅ 简单（搜索常量）     |
+| **统计性**   | ❌ 不可能             | ✅ 容易（统计 Key）     |
+| **类型安全** | ❌ 没有               | ✅ 有（TypeScript）     |
+| **心智负担** | ❌ 高（需记住文字）   | ✅ 低（只需记变量名）   |
+| **IDE 支持** | ❌ 无自动补全         | ✅ 完整自动补全         |
+
+### ⭐ 核心优势：减少开发者思考
+
+**最重要的优势：开发者不需要关心具体的 i18n 字符串是什么！**
+
+```typescript
+// ❌ 传统方式：需要记住复杂的字符串
+function LoginPage() {
+  const { t } = useTranslation();
+
+  return (
+    <div>
+      {/* 😰 需要记住 'common:button.login' */}
+      <button>{t('common:button.login')}</button>
+
+      {/* 😰 需要记住 'page.login.title' */}
+      <h1>{t('page.login.title')}</h1>
+
+      {/* 😰 写错了也不会报错 */}
+      <p>{t('page.login.welcom')}</p>  {/* welcom → welcome，拼写错误 */}
+    </div>
+  );
+}
+
+// ✅ i18n Key 方式：只需要知道变量名
+import { BUTTON_LOGIN, PAGE_LOGIN_TITLE, PAGE_LOGIN_WELCOME } from '@config/Identifier';
+
+function LoginPage() {
+  const { t } = useAppTranslation();
+
+  return (
+    <div>
+      {/* ✅ 只需要记住 BUTTON_LOGIN，IDE 会自动补全 */}
+      <button>{t(BUTTON_LOGIN)}</button>
+
+      {/* ✅ 输入 PAGE_ 后，IDE 会提示所有可用的 Key */}
+      <h1>{t(PAGE_LOGIN_TITLE)}</h1>
+
+      {/* ✅ 写错了 TypeScript 会立即报错 */}
+      <p>{t(PAGE_LOGIN_WELCOM)}</p>  {/* ❌ TS 错误：找不到变量 */}
+    </div>
+  );
+}
+```
+
+**开发体验对比：**
+
+```typescript
+// ❌ 使用字符串的开发流程：
+// 1. 😰 查看翻译文件，找到对应的 key
+// 2. 😰 记住 key 的完整路径（如 'common:page.login.title'）
+// 3. 😰 在代码中手动输入字符串
+// 4. 😰 可能输入错误，但编译器不会报错
+// 5. 😰 运行时才发现翻译没有生效
+
+// ✅ 使用 i18n Key 的开发流程：
+// 1. 😊 输入变量名前缀（如 BUTTON_）
+// 2. 😊 IDE 自动提示所有可用的 Key
+// 3. 😊 选择需要的 Key，IDE 自动补全
+// 4. 😊 如果输入错误，TypeScript 立即报错
+// 5. 😊 编译期就能确保 Key 的正确性
+```
+
+**认知负担对比：**
+
+| 开发者需要记住的内容 | 字符串方式                              | i18n Key 方式   |
+| -------------------- | --------------------------------------- | --------------- |
+| **翻译文件结构**     | ✅ 必须记住（如 `common:button.login`） | ❌ 不需要记     |
+| **命名空间**         | ✅ 必须记住（如 `common:`, `page:`）    | ❌ 不需要记     |
+| **字符串路径**       | ✅ 必须记住完整路径                     | ❌ 不需要记     |
+| **变量名**           | ❌ 没有变量                             | ✅ 只需记变量名 |
+| **IDE 提示**         | ❌ 没有                                 | ✅ 完整提示     |
+
+**实际开发场景：**
+
+```typescript
+// 场景 1：新写一个按钮
+
+// ❌ 字符串方式（需要思考很多）
+// 1. 这个按钮的翻译 key 应该叫什么？
+// 2. 应该放在哪个命名空间？common? page?
+// 3. 路径应该是什么？button.submit? submit.button?
+// 4. 最终写出：t('common:button.submit')
+<button>{t('common:button.submit')}</button>
+
+// ✅ i18n Key 方式（只需要搜索）
+// 1. 输入 BUTTON_
+// 2. IDE 显示所有可用的按钮 Key
+// 3. 看到 BUTTON_SUBMIT，选择它
+// 4. 完成！
+<button>{t(BUTTON_SUBMIT)}</button>
+
+// 场景 2：要改另一个页面的文字
+
+// ❌ 字符串方式
+// 1. 查看那个页面的代码
+// 2. 找到 t('page.home.welcome')
+// 3. 记住这个字符串
+// 4. 在翻译文件中搜索并修改
+
+// ✅ i18n Key 方式
+// 1. 看到代码中的 PAGE_HOME_WELCOME
+// 2. 直接跳转到定义（IDE 的 Go to Definition）
+// 3. 修改注释中的翻译
+// 4. 自动生成新的翻译文件
+```
+
+**总结：**
+
+使用 i18n Key 让开发者：
+
+- ✅ **不需要记住** 复杂的字符串路径
+- ✅ **不需要记住** 翻译文件的结构
+- ✅ **不需要关心** 具体的翻译键名
+- ✅ **只需要知道** 这是一个变量
+- ✅ **依靠 IDE** 提供的自动补全和类型检查
+- ✅ **专注于** 业务逻辑，而不是翻译细节
+
+> 💡 **核心理念：让开发者把精力用在业务逻辑上，而不是记忆翻译字符串！**
+
+---
+
+## 🛠️ 项目中的实现
+
+### 1. 文件结构
+
+```
+config/
+└── Identifier/           # i18n Key 定义目录
+    ├── index.ts          # 导出所有 Key
+    ├── common/           # 公共文本
+    │   ├── index.ts
+    │   ├── common.ts     # 通用文本（按钮、消息等）
+    │   └── common.error.ts # 错误信息
+    └── pages/            # 页面文本
+        ├── index.ts
+        ├── page.home.ts  # 首页文本
+        ├── page.login.ts # 登录页文本
+        └── page.about.ts # 关于页文本
+
+public/
+└── locales/              # 生成的翻译文件
+    ├── zh/
+    │   └── common.json   # 中文翻译
+    └── en/
+        └── common.json   # 英文翻译
+
+src/
+└── uikit/
+    └── hooks/
+        └── useAppTranslation.ts  # 翻译 Hook
 ```
 
-### 3. i18n 服务配置
+### 2. i18n 配置
 
 ```typescript
-// config/i18n.ts
-export default {
-  fallbackLng: 'en',
+// config/i18n/i18nConfig.ts
+export const i18nConfig = {
+  fallbackLng: 'en', // 默认语言
   debug: false,
   interpolation: {
     escapeValue: false
   },
-  ns: ['common'],
+  ns: ['common'], // 命名空间
   defaultNS: 'common',
   backend: {
-    loadPath: '/locales/{{lng}}/{{ns}}.json'
+    loadPath: '/locales/{{lng}}/{{ns}}.json' // 翻译文件路径
   },
-  supportedLngs: ['en', 'zh']
+  supportedLngs: ['en', 'zh'] // 支持的语言
 } as const;
 ```
 
-## 使用方式
+### 3. I18nService（Bootstrap 插件）
 
-### 1. 定义翻译键
+```typescript
+// src/base/services/I18nService.ts
+export class I18nService implements BootstrapExecutorPlugin {
+  readonly pluginName = 'I18nService';
+
+  constructor(protected pathname: string) {
+    super(() => new I18nServiceState(i18n.language));
+  }
+
+  /**
+   * 在 Bootstrap 启动时初始化 i18n
+   */
+  onBefore(): void {
+    i18n
+      .use(HttpApi) // 加载翻译文件
+      .use(LanguageDetector) // 语言检测
+      .use(initReactI18next) // React 集成
+      .init(i18nConfig); // 初始化配置
+
+    // 添加自定义语言检测器（从 URL 路径检测）
+    const pathLanguageDetector = {
+      name: 'pathLanguageDetector',
+      lookup: () => {
+        const paths = this.pathname.split('/');
+        for (const path of paths) {
+          if (this.isValidLanguage(path)) {
+            return path; // 从 URL 中提取语言（如 /zh/home）
+          }
+        }
+        return fallbackLng;
+      },
+      cacheUserLanguage(lng: string) {
+        localStorage.setItem('i18nextLng', lng);
+      }
+    };
+
+    i18n.services.languageDetector.addDetector(pathLanguageDetector);
+  }
+
+  /**
+   * 切换语言
+   */
+  async changeLanguage(language: string): Promise<void> {
+    await i18n.changeLanguage(language);
+    localStorage.setItem('i18nextLng', language);
+  }
+
+  /**
+   * 翻译文本
+   */
+  t(key: string, params?: Record<string, unknown>): string {
+    return i18n.t(key, { lng: i18n.language, ...params });
+  }
+}
+```
+
+### 4. 自动生成翻译文件
 
 ```typescript
-// config/Identifier/page.ts
+// vite.config.ts
+import ts2Locales from '@brain-toolkit/ts2locales/vite';
+
+export default defineConfig({
+  plugins: [
+    // ✅ ts2locales 插件：自动从 TypeScript 注释生成翻译文件
+    ts2Locales({
+      locales: ['en', 'zh'],
+      options: generateTs2LocalesOptions() // 配置生成规则
+    })
+  ]
+});
+```
+
+**工作原理：**
+
+```typescript
+// 1. 在 Identifier 文件中定义 Key
+/**
+ * @description Login button text
+ * @localZh 登录
+ * @localEn Login
+ */
+export const BUTTON_LOGIN = 'common:button.login';
+
+// 2. ts2locales 插件自动生成翻译文件
+
+// public/locales/zh/common.json
+{
+  "button": {
+    "login": "登录"
+  }
+}
+
+// public/locales/en/common.json
+{
+  "button": {
+    "login": "Login"
+  }
+}
+```
+
+---
+
+## 📝 使用方式
+
+### 1. 定义 i18n Key
+
+```typescript
+// config/Identifier/pages/page.home.ts
 
 /**
  * @description Home page title
  * @localZh 首页
  * @localEn Home
  */
-export const PAGE_HOME_TITLE = 'page.home.title';
+export const PAGE_HOME_TITLE = 'common:page.home.title';
 
 /**
  * @description Home page welcome message
- * @localZh 欢迎来到我们的应用
- * @localEn Welcome to our application
+ * @localZh 欢迎来到我们的应用！
+ * @localEn Welcome to our application!
  */
-export const PAGE_HOME_WELCOME = 'page.home.welcome';
+export const PAGE_HOME_WELCOME = 'common:page.home.welcome';
+
+/**
+ * @description Home page description with user name
+ * @localZh 你好，{{name}}！今天是个好日子。
+ * @localEn Hello, {{name}}! Have a great day.
+ */
+export const PAGE_HOME_GREETING = 'common:page.home.greeting';
 ```
 
-### 2. 在组件中使用
+**注释规范：**
+
+- `@description`：说明文本用途（英文）
+- `@localZh`：中文翻译
+- `@localEn`：英文翻译
 
-```tsx
-import { useTranslation } from 'react-i18next';
-import * as i18nKeys from '@config/Identifier/page';
+### 2. 在 UI 组件中使用
+
+```typescript
+// src/pages/base/HomePage.tsx
+import { useAppTranslation } from '@/uikit/hooks/useAppTranslation';
+import {
+  PAGE_HOME_TITLE,
+  PAGE_HOME_WELCOME,
+  PAGE_HOME_GREETING
+} from '@config/Identifier';
 
 function HomePage() {
-  const { t } = useTranslation();
+  const { t } = useAppTranslation();
+  const userName = 'John';
 
   return (
     <div>
-      <h1>{t(i18nKeys.PAGE_HOME_TITLE)}</h1>
-      <p>{t(i18nKeys.PAGE_HOME_WELCOME)}</p>
+      {/* ✅ 简单文本 */}
+      <h1>{t(PAGE_HOME_TITLE)}</h1>
+      <p>{t(PAGE_HOME_WELCOME)}</p>
+
+      {/* ✅ 带参数的文本 */}
+      <p>{t(PAGE_HOME_GREETING, { name: userName })}</p>
     </div>
   );
 }
 ```
 
-### 3. 带参数的翻译
+### 3. 在服务中使用
 
 ```typescript
-/**
- * @description Welcome user message
- * @localZh 欢迎，{{name}}！
- * @localEn Welcome, {{name}}!
- */
-export const USER_WELCOME = 'user.welcome';
-
-function Welcome({ username }: { username: string }) {
-  const { t } = useTranslation();
-  return <h1>{t(i18nKeys.USER_WELCOME, { name: username })}</h1>;
+// src/base/services/UserService.ts
+import { injectable, inject } from 'inversify';
+import { I18nServiceInterface } from '@/base/port/I18nServiceInterface';
+import { ERROR_USER_NOT_FOUND } from '@config/Identifier';
+
+@injectable()
+export class UserService {
+  constructor(
+    @inject(IOCIdentifier.I18nServiceInterface)
+    private i18n: I18nServiceInterface
+  ) {}
+
+  async getUser(id: string) {
+    const user = await this.api.getUserById(id);
+
+    if (!user) {
+      // ✅ 在服务中使用 i18n
+      throw new Error(this.i18n.t(ERROR_USER_NOT_FOUND, { id }));
+    }
+
+    return user;
+  }
 }
 ```
 
-### 4. 语言切换
+### 4. 切换语言
 
-```tsx
-import { IOC } from '@/core/IOC';
-import { I18nService } from '@/base/services/I18nService';
+```typescript
+// src/uikit/components/LanguageSwitcher.tsx
+import { useIOC } from '@/uikit/hooks/useIOC';
 
 function LanguageSwitcher() {
-  const i18nService = IOC(I18nService);
+  const i18nService = useIOC('I18nServiceInterface');
   const currentLang = i18nService.getCurrentLanguage();
 
-  const handleChange = (lang: string) => {
+  const handleChange = (lang: 'zh' | 'en') => {
+    // ✅ 切换语言
     i18nService.changeLanguage(lang);
   };
 
@@ -159,110 +575,405 @@ function LanguageSwitcher() {
 }
 ```
 
-## 最佳实践
+### 5. 复杂场景
 
-### 1. 标识符组织
+#### 场景 1：动态文本
 
-- **命名规范**：
+```typescript
+/**
+ * @description Upload progress message
+ * @localZh 已上传 {{current}} / {{total}} 个文件
+ * @localEn Uploaded {{current}} / {{total}} files
+ */
+export const UPLOAD_PROGRESS = 'common:upload.progress';
 
-  ```typescript
-  // 页面相关
-  PAGE_HOME_TITLE;
-  PAGE_ABOUT_DESCRIPTION;
+// 使用
+<p>{t(UPLOAD_PROGRESS, { current: 3, total: 10 })}</p>
+// 中文：已上传 3 / 10 个文件
+// 英文：Uploaded 3 / 10 files
+```
 
-  // 功能模块相关
-  AUTH_LOGIN_BUTTON;
-  AUTH_LOGOUT_CONFIRM;
+#### 场景 2：复数形式
 
-  // 公共组件相关
-  COMMON_SUBMIT_BUTTON;
-  COMMON_CANCEL_BUTTON;
-  ```
+```typescript
+/**
+ * @description Files count message
+ * @localZh {{count}} 个文件
+ * @localEn {{count}} file_plural
+ */
+export const FILES_COUNT = 'common:files.count';
 
-- **文件组织**：
-  ```
-  config/
-  ├── Identifier/
-  │   ├── common.ts     // 公共文本
-  │   ├── page.ts       // 页面文本
-  │   ├── error.ts      // 错误信息
-  │   └── auth.ts       // 认证相关
-  ```
+// 使用
+<p>{t(FILES_COUNT, { count: 1 })}</p>  // 1 file
+<p>{t(FILES_COUNT, { count: 5 })}</p>  // 5 files
+```
 
-### 2. 注释规范
+#### 场景 3：HTML 内容
 
 ```typescript
 /**
- * @description 简短的描述，说明文本用途
- * @localZh 中文翻译文本
- * @localEn 英文翻译文本
+ * @description Terms of service agreement
+ * @localZh 我已阅读并同意<a href="/terms">服务条款</a>
+ * @localEn I have read and agree to the <a href="/terms">Terms of Service</a>
  */
+export const TERMS_AGREEMENT = 'common:terms.agreement';
+
+// 使用（React 中需要使用 Trans 组件）
+import { Trans } from 'react-i18next';
+
+<Trans i18nKey={TERMS_AGREEMENT}>
+  I have read and agree to the <a href="/terms">Terms of Service</a>
+</Trans>
+```
+
+---
+
+## 💎 最佳实践
+
+### 1. ✅ 所有文本都使用 i18n Key
+
+```typescript
+// ❌ 错误：混用硬编码和 i18n Key
+function LoginForm() {
+  return (
+    <form>
+      <h1>{t(PAGE_LOGIN_TITLE)}</h1>
+      <button>登录</button>  {/* ❌ 硬编码 */}
+      <a href="/forgot">忘记密码？</a>  {/* ❌ 硬编码 */}
+    </form>
+  );
+}
+
+// ✅ 正确：所有文本都使用 i18n Key
+function LoginForm() {
+  return (
+    <form>
+      <h1>{t(PAGE_LOGIN_TITLE)}</h1>
+      <button>{t(BUTTON_LOGIN)}</button>  {/* ✅ 使用 Key */}
+      <a href="/forgot">{t(LINK_FORGOT_PASSWORD)}</a>  {/* ✅ 使用 Key */}
+    </form>
+  );
+}
 ```
 
-### 3. 类型安全
+### 2. ✅ 合理组织 i18n Key
 
 ```typescript
-// 使用类型导入确保键值存在
-import * as i18nKeys from '@config/Identifier';
+// ✅ 好的组织：按功能模块分类
+config/Identifier/
+├── common/
+│   ├── common.ts           # 通用文本（按钮、标签等）
+│   └── common.error.ts     # 错误信息
+├── pages/
+│   ├── page.home.ts        # 首页文本
+│   ├── page.login.ts       # 登录页文本
+│   └── page.about.ts       # 关于页文本
+└── components/
+    ├── component.header.ts # 头部组件文本
+    └── component.footer.ts # 底部组件文本
+```
+
+### 3. ✅ 使用语义化的命名
 
-// 类型检查会捕获错误的键值
-t(i18nKeys.NONEXISTENT_KEY); // TS 错误
+```typescript
+// ✅ 好的命名：清晰表达含义
+export const BUTTON_SUBMIT = 'common:button.submit';
+export const BUTTON_CANCEL = 'common:button.cancel';
+export const ERROR_NETWORK = 'common:error.network';
+export const MESSAGE_SUCCESS = 'common:message.success';
+
+// ❌ 不好的命名：含义不清
+export const BTN1 = 'btn1';
+export const TEXT = 'text';
+export const MSG = 'msg';
 ```
 
-### 4. 动态内容
+### 4. ✅ 为 i18n Key 添加清晰的注释
 
 ```typescript
+// ✅ 好的注释：清晰说明用途和上下文
+/**
+ * @description Confirmation message when user tries to delete an item
+ * @localZh 确定要删除 {{itemName}} 吗？此操作不可撤销。
+ * @localEn Are you sure you want to delete {{itemName}}? This action cannot be undone.
+ */
+export const CONFIRM_DELETE_ITEM = 'common:confirm.delete.item';
+
+// ❌ 不好的注释：没有上下文信息
 /**
- * @description File upload progress
- * @localZh 已上传 {{count}} 个文件，共 {{total}} 个
- * @localEn Uploaded {{count}} files out of {{total}}
+ * @description Delete
+ * @localZh 删除
+ * @localEn Delete
  */
-export const UPLOAD_PROGRESS = 'upload.progress';
+export const DELETE = 'delete';
+```
+
+### 5. ✅ 统一命名规范
+
+```typescript
+// ✅ 推荐的命名规范：
+
+// 按钮文本
+export const BUTTON_LOGIN = 'common:button.login';
+export const BUTTON_SUBMIT = 'common:button.submit';
+export const BUTTON_CANCEL = 'common:button.cancel';
+
+// 页面标题
+export const PAGE_HOME_TITLE = 'common:page.home.title';
+export const PAGE_ABOUT_TITLE = 'common:page.about.title';
+
+// 错误信息
+export const ERROR_NETWORK = 'common:error.network';
+export const ERROR_INVALID_INPUT = 'common:error.invalid.input';
+
+// 消息提示
+export const MESSAGE_SUCCESS = 'common:message.success';
+export const MESSAGE_WARNING = 'common:message.warning';
+
+// 确认对话框
+export const CONFIRM_DELETE = 'common:confirm.delete';
+export const CONFIRM_LOGOUT = 'common:confirm.logout';
+
+// 链接文本
+export const LINK_FORGOT_PASSWORD = 'common:link.forgot.password';
+export const LINK_PRIVACY_POLICY = 'common:link.privacy.policy';
+```
+
+### 6. ✅ 避免重复定义
+
+```typescript
+// ❌ 错误：重复定义相同的文本
+// config/Identifier/common/common.ts
+export const BUTTON_OK_1 = 'common:button.ok1';
+
+// config/Identifier/pages/page.home.ts
+export const BUTTON_OK_2 = 'common:button.ok2';
+
+// ✅ 正确：在公共文件中定义一次，多处引用
+// config/Identifier/common/common.ts
+export const BUTTON_OK = 'common:button.ok';
+
+// 在各个页面中引用
+import { BUTTON_OK } from '@config/Identifier';
+```
+
+### 7. ✅ 使用参数化文本
+
+```typescript
+// ❌ 不好：为每种情况定义不同的 Key
+export const WELCOME_USER_JOHN = 'common:welcome.john';
+export const WELCOME_USER_MARY = 'common:welcome.mary';
+
+// ✅ 好：使用参数
+/**
+ * @description Welcome message with user name
+ * @localZh 欢迎，{{name}}！
+ * @localEn Welcome, {{name}}!
+ */
+export const WELCOME_USER = 'common:welcome.user';
 
 // 使用
-t(i18nKeys.UPLOAD_PROGRESS, { count: 3, total: 10 });
+<h1>{t(WELCOME_USER, { name: 'John' })}</h1>
+<h1>{t(WELCOME_USER, { name: 'Mary' })}</h1>
 ```
 
-## 工作流程
+---
 
-1. **开发阶段**：
-   - 在 Identifier 文件中定义翻译键和注释
-   - 使用标识符别名在代码中引用翻译
-   - 运行开发服务器时自动生成翻译文件
+## ❓ 常见问题
 
-2. **构建阶段**：
-   - 自动检查翻译完整性
-   - 生成生产环境翻译文件
-   - 优化翻译资源加载
+### Q1: 为什么不能直接写文字？
 
-3. **运行时**：
-   - 根据 URL 检测语言
-   - 按需加载翻译资源
-   - 响应语言切换事件
+**A:**
 
-## 常见问题
+```typescript
+// ❌ 直接写文字的问题
+<button>登录</button>
 
-### 1. 翻译未生效
+// 问题 1：无法国际化
+// 如果用户切换到英文，文字不会改变
 
-检查以下几点：
+// 问题 2：难以维护
+// 如果要把"登录"改成"立即登录"，需要找到所有地方修改
 
-- 确保标识符正确导出
-- 检查注释格式是否规范
-- 验证翻译文件是否生成
-- 确认语言检测正确
+// 问题 3：无法统一管理
+// 无法知道项目中有多少个"登录"按钮
 
-### 2. 类型错误
+// ✅ 使用 i18n Key 的优势
+<button>{t(BUTTON_LOGIN)}</button>
 
-可能的解决方案：
+// ✅ 自动国际化：切换语言自动显示对应文本
+// ✅ 易于维护：只需修改一处定义
+// ✅ 统一管理：所有文本集中在 Identifier 文件中
+```
+
+### Q2: 如何知道某个 Key 在哪里使用？
+
+**A:**
+
+```bash
+# 搜索常量名
+grep -r "BUTTON_LOGIN" src/
 
-- 检查标识符导入路径
-- 确保使用正确的标识符
-- 更新 TypeScript 类型定义
+# 或者在 IDE 中使用 "Find Usages" 功能
+# 可以快速找到所有使用该 Key 的地方
+```
+
+### Q3: 忘记定义 i18n Key 怎么办？
 
-### 3. 性能优化
+**A:** TypeScript 会在编译时报错：
+
+```typescript
+// ❌ 使用未定义的 Key
+<button>{t(BUTTON_NOT_EXIST)}</button>
+// TypeScript 错误：Cannot find name 'BUTTON_NOT_EXIST'
+
+// ✅ 正确：先定义 Key
+export const BUTTON_NOT_EXIST = 'common:button.not.exist';
+```
+
+### Q4: 如何处理动态文本？
+
+**A:** 使用参数：
+
+```typescript
+/**
+ * @description User greeting with name and time
+ * @localZh {{name}}，{{time}}好！
+ * @localEn Good {{time}}, {{name}}!
+ */
+export const GREETING_WITH_TIME = 'common:greeting.with.time';
+
+// 使用
+<h1>{t(GREETING_WITH_TIME, { name: 'John', time: 'morning' })}</h1>
+// 中文：John，morning好！
+// 英文：Good morning, John!
+```
+
+### Q5: 翻译文件是如何生成的？
+
+**A:**
+
+```
+1. 开发者在 Identifier 文件中定义 Key 和翻译注释
+   ↓
+2. ts2locales 插件扫描 TypeScript 文件
+   ↓
+3. 从注释中提取 @localZh 和 @localEn
+   ↓
+4. 自动生成 public/locales/{lng}/common.json
+   ↓
+5. i18next 在运行时加载这些 JSON 文件
+```
+
+### Q6: 可以在代码中直接使用翻译后的文本吗？
+
+**A:**
+
+```typescript
+// ❌ 不推荐：跳过 i18n 系统
+const loginText = '登录';  // 硬编码
+<button>{loginText}</button>
+
+// ✅ 推荐：始终使用 i18n Key
+const loginText = t(BUTTON_LOGIN);  // 通过 i18n 系统
+<button>{loginText}</button>
+```
+
+### Q7: 如何测试 i18n？
+
+**A:**
+
+```typescript
+// __tests__/i18n.test.ts
+import { I18nService } from '@/base/services/I18nService';
+import { BUTTON_LOGIN } from '@config/Identifier';
+
+describe('I18n', () => {
+  let i18nService: I18nService;
+
+  beforeEach(() => {
+    i18nService = new I18nService('/zh/home');
+    i18nService.onBefore();
+  });
+
+  it('should translate to Chinese', () => {
+    i18nService.changeLanguage('zh');
+    expect(i18nService.t(BUTTON_LOGIN)).toBe('登录');
+  });
+
+  it('should translate to English', () => {
+    i18nService.changeLanguage('en');
+    expect(i18nService.t(BUTTON_LOGIN)).toBe('Login');
+  });
+
+  it('should support parameters', () => {
+    const result = i18nService.t(WELCOME_USER, { name: 'John' });
+    expect(result).toContain('John');
+  });
+});
+```
+
+---
+
+## 📚 相关文档
+
+- [项目架构设计](./index.md) - 了解整体架构
+- [Bootstrap 启动器](./bootstrap.md) - I18nService 是 Bootstrap 插件之一
+- [配置驱动开发](./#配置驱动开发) - i18n Key 是配置驱动的实践
+
+---
+
+## 🎉 总结
+
+国际化系统的核心理念：
+
+1. **唯一标识符** 🔑 - 每个文本都有唯一的 i18n Key
+2. **绝不硬编码** 🚫 - 项目中所有文本都必须使用 i18n Key
+3. **减少思考** 🧠 - 开发者只需知道变量名，不需要记住字符串路径
+4. **集中管理** 📦 - 所有 Key 定义在 Identifier 目录中
+5. **自动生成** ⚡ - 翻译文件从注释自动生成
+6. **类型安全** 🔒 - TypeScript 提供完整的类型检查
+7. **易于维护** 🛠️ - 修改翻译只需修改一处
+8. **IDE 友好** 💻 - 完整的自动补全和类型提示
+
+**记住两个核心原则：**
+
+1. **永远不要在代码中直接写文字！**
+2. **开发者不需要记住翻译字符串，只需要知道变量名！**
+
+```typescript
+// ❌ 永远不要这样做
+<button>登录</button>
+<h1>欢迎回来</h1>
+<p>{t('common:confirm.delete')}</p>  // 也不要直接写字符串
+
+// ✅ 始终这样做
+<button>{t(BUTTON_LOGIN)}</button>
+<h1>{t(MESSAGE_WELCOME)}</h1>
+<p>{t(CONFIRM_DELETE)}</p>  // 使用变量，IDE 会自动补全
+```
+
+**开发流程：**
+
+```typescript
+// 1. 输入变量名前缀
+t(BUTTON_
+
+// 2. IDE 自动提示所有可用的 Key
+// BUTTON_LOGIN
+// BUTTON_SUBMIT
+// BUTTON_CANCEL
+// ...
+
+// 3. 选择需要的 Key，完成！
+t(BUTTON_LOGIN)
+
+// 不需要记住 'common:button.login'
+// 不需要关心翻译文件的结构
+// 不需要担心拼写错误（TypeScript 会检查）
+```
 
-开发建议：
+---
 
-- 合理拆分翻译文件
-- 使用翻译资源预加载
-- 避免重复翻译键
+**问题反馈：**  
+如果你对国际化系统有任何疑问或建议，请在团队频道中讨论或提交 Issue。