@qlover/create-app 1.1.0 → 2.0.0

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

@@ -1,979 +0,0 @@
-# 国际化 (i18n)
-
-## 📋 目录
-
-- [核心理念](#-核心理念) - 绝不硬编码，只用变量
-- [什么是 i18n Key](#-什么是-i18n-key) - 唯一标识符
-- [为什么使用 i18n Key](#-为什么使用-i18n-key) - 减少思考负担
-- [项目中的实现](#-项目中的实现) - Bootstrap 插件
-- [使用方式](#-使用方式) - 实战指南
-- [最佳实践](#-最佳实践) - 7 条核心实践
-- [常见问题](#-常见问题) - FAQ
-
----
-
-## 🎯 核心理念
-
-> **🚨 重要原则：项目中所有需要显示的文字、词语、句子，都必须使用 i18n Key，绝不允许硬编码文本！**
-
-> **⭐ 核心优势：开发者不需要记住复杂的翻译字符串，只需要知道变量名，IDE 会提供自动补全！**
-
-### 核心概念
-
-```
-❌ 硬编码文本        ✅ i18n Key（变量）
-"登录"          →   BUTTON_LOGIN (不需要记住 'common:button.login')
-"欢迎回来"       →   MESSAGE_WELCOME (不需要记住 'common:message.welcome')
-"确定要删除吗？" →   CONFIRM_DELETE (不需要记住 'common:confirm.delete')
-```
-
-**每个文本都有唯一的标识符：**
-
-```typescript
-// ❌ 错误：直接写文字或字符串
-<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 Login button text
- * @localZh 登录
- * @localEn Login
- */
-export const BUTTON_LOGIN = 'common:button.login';
-//            ↑ 常量名                 ↑ 标识符字符串
-//            用于代码中引用          存储在翻译文件中的键名
-
-/**
- * @description Welcome message
- * @localZh 欢迎回来，{{name}}！
- * @localEn Welcome back, {{name}}!
- */
-export const MESSAGE_WELCOME = 'common:message.welcome';
-```
-
-**结构说明：**
-
-```
-'common:button.login'
-   ↑      ↑      ↑
-命名空间  分类   具体标识
-```
-
-### 命名规范
-
-```typescript
-// ✅ 好的命名：清晰、结构化
-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';
-```
-
----
-
-## 🤔 为什么使用 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
-```
-
-### 2. i18n 配置
-
-```typescript
-// config/i18n/i18nConfig.ts
-export const i18nConfig = {
-  fallbackLng: 'en', // 默认语言
-  debug: false,
-  interpolation: {
-    escapeValue: false
-  },
-  ns: ['common'], // 命名空间
-  defaultNS: 'common',
-  backend: {
-    loadPath: '/locales/{{lng}}/{{ns}}.json' // 翻译文件路径
-  },
-  supportedLngs: ['en', 'zh'] // 支持的语言
-} as const;
-```
-
-### 3. I18nService（Bootstrap 插件）
-
-```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
-// 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 = 'common:page.home.title';
-
-/**
- * @description Home page welcome message
- * @localZh 欢迎来到我们的应用！
- * @localEn Welcome to our application!
- */
-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';
-```
-
-**注释规范：**
-
-- `@description`：说明文本用途（英文）
-- `@localZh`：中文翻译
-- `@localEn`：英文翻译
-
-### 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 } = useAppTranslation();
-  const userName = 'John';
-
-  return (
-    <div>
-      {/* ✅ 简单文本 */}
-      <h1>{t(PAGE_HOME_TITLE)}</h1>
-      <p>{t(PAGE_HOME_WELCOME)}</p>
-
-      {/* ✅ 带参数的文本 */}
-      <p>{t(PAGE_HOME_GREETING, { name: userName })}</p>
-    </div>
-  );
-}
-```
-
-### 3. 在服务中使用
-
-```typescript
-// 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. 切换语言
-
-```typescript
-// src/uikit/components/LanguageSwitcher.tsx
-import { useIOC } from '@/uikit/hooks/useIOC';
-
-function LanguageSwitcher() {
-  const i18nService = useIOC('I18nServiceInterface');
-  const currentLang = i18nService.getCurrentLanguage();
-
-  const handleChange = (lang: 'zh' | 'en') => {
-    // ✅ 切换语言
-    i18nService.changeLanguage(lang);
-  };
-
-  return (
-    <select value={currentLang} onChange={(e) => handleChange(e.target.value)}>
-      <option value="zh">中文</option>
-      <option value="en">English</option>
-    </select>
-  );
-}
-```
-
-### 5. 复杂场景
-
-#### 场景 1：动态文本
-
-```typescript
-/**
- * @description Upload progress message
- * @localZh 已上传 {{current}} / {{total}} 个文件
- * @localEn Uploaded {{current}} / {{total}} files
- */
-export const UPLOAD_PROGRESS = 'common:upload.progress';
-
-// 使用
-<p>{t(UPLOAD_PROGRESS, { current: 3, total: 10 })}</p>
-// 中文：已上传 3 / 10 个文件
-// 英文：Uploaded 3 / 10 files
-```
-
-#### 场景 2：复数形式
-
-```typescript
-/**
- * @description Files count message
- * @localZh {{count}} 个文件
- * @localEn {{count}} file_plural
- */
-export const FILES_COUNT = 'common:files.count';
-
-// 使用
-<p>{t(FILES_COUNT, { count: 1 })}</p>  // 1 file
-<p>{t(FILES_COUNT, { count: 5 })}</p>  // 5 files
-```
-
-#### 场景 3：HTML 内容
-
-```typescript
-/**
- * @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>
-  );
-}
-```
-
-### 2. ✅ 合理组织 i18n Key
-
-```typescript
-// ✅ 好的组织：按功能模块分类
-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. ✅ 使用语义化的命名
-
-```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. ✅ 为 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 Delete
- * @localZh 删除
- * @localEn Delete
- */
-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';
-
-// 使用
-<h1>{t(WELCOME_USER, { name: 'John' })}</h1>
-<h1>{t(WELCOME_USER, { name: 'Mary' })}</h1>
-```
-
----
-
-## ❓ 常见问题
-
-### Q1: 为什么不能直接写文字？
-
-**A:**
-
-```typescript
-// ❌ 直接写文字的问题
-<button>登录</button>
-
-// 问题 1：无法国际化
-// 如果用户切换到英文，文字不会改变
-
-// 问题 2：难以维护
-// 如果要把"登录"改成"立即登录"，需要找到所有地方修改
-
-// 问题 3：无法统一管理
-// 无法知道项目中有多少个"登录"按钮
-
-// ✅ 使用 i18n Key 的优势
-<button>{t(BUTTON_LOGIN)}</button>
-
-// ✅ 自动国际化：切换语言自动显示对应文本
-// ✅ 易于维护：只需修改一处定义
-// ✅ 统一管理：所有文本集中在 Identifier 文件中
-```
-
-### Q2: 如何知道某个 Key 在哪里使用？
-
-**A:**
-
-```bash
-# 搜索常量名
-grep -r "BUTTON_LOGIN" src/
-
-# 或者在 IDE 中使用 "Find Usages" 功能
-# 可以快速找到所有使用该 Key 的地方
-```
-
-### Q3: 忘记定义 i18n Key 怎么办？
-
-**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。