@qlover/create-app 1.0.2 → 2.0.0

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

@@ -1,979 +0,0 @@
-# Internationalization (i18n)
-
-## 📋 Table of Contents
-
-- [Core Philosophy](#-core-philosophy) - Never hard-code, use variables only
-- [What is an i18n Key](#-what-is-an-i18n-key) - Unique identifier
-- [Why Use i18n Keys](#-why-use-i18n-keys) - Reduce cognitive burden
-- [Implementation in the Project](#-implementation-in-the-project) - Bootstrap plugin
-- [How to Use](#-how-to-use) - Practical guide
-- [Best Practices](#-best-practices) - 7 core practices
-- [FAQ](#-faq) - Common questions
-
----
-
-## 🎯 Core Philosophy
-
-> **🚨 Important Principle: All text, words, and sentences that need to be displayed in the project must use i18n Keys. Hard-coded text is absolutely not allowed!**
-
-> **⭐ Core Advantage: Developers don't need to remember complex translation strings, just variable names. The IDE will provide auto-completion!**
-
-### Core Concept
-
-```
-❌ Hard-coded text        ✅ i18n Key (variable)
-"Login"            →   BUTTON_LOGIN (no need to remember 'common:button.login')
-"Welcome back"     →   MESSAGE_WELCOME (no need to remember 'common:message.welcome')
-"Are you sure?"    →   CONFIRM_DELETE (no need to remember 'common:confirm.delete')
-```
-
-**Every text has a unique identifier:**
-
-```typescript
-// ❌ Wrong: Write text directly or use strings
-<button>Login</button>
-<h1>Welcome back</h1>
-<p>{t('common:confirm.delete')}</p>  // Don't write strings either
-
-// ✅ Correct: Use i18n Key variables
-<button>{t(BUTTON_LOGIN)}</button>       // Just remember the variable name
-<h1>{t(MESSAGE_WELCOME)}</h1>            // IDE will auto-complete
-<p>{t(CONFIRM_DELETE)}</p>               // TypeScript will check spelling
-```
-
----
-
-## 🔑 What is an i18n Key
-
-An i18n Key is **a unique identifier for each text**, just like everyone has an ID number.
-
-### Basic Concept
-
-```typescript
-// i18n Key definition (in config/Identifier/ directory)
-
-/**
- * @description Login button text
- * @localZh 登录
- * @localEn Login
- */
-export const BUTTON_LOGIN = 'common:button.login';
-//            ↑ Constant name            ↑ Identifier string
-//            Used in code               Key name stored in translation files
-
-/**
- * @description Welcome message
- * @localZh 欢迎回来，{{name}}！
- * @localEn Welcome back, {{name}}!
- */
-export const MESSAGE_WELCOME = 'common:message.welcome';
-```
-
-**Structure explanation:**
-
-```
-'common:button.login'
-   ↑      ↑      ↑
-Namespace Category Specific identifier
-```
-
-### Naming Conventions
-
-```typescript
-// ✅ Good naming: Clear and structured
-export const BUTTON_LOGIN = 'common:button.login'; // Button text
-export const BUTTON_SUBMIT = 'common:button.submit'; // Button text
-export const MESSAGE_WELCOME = 'common:message.welcome'; // Message text
-export const CONFIRM_DELETE = 'common:confirm.delete'; // Confirm dialog
-export const ERROR_NETWORK = 'common:error.network'; // Error message
-export const PAGE_HOME_TITLE = 'common:page.home.title'; // Page title
-
-// ❌ Bad naming: Vague and unstructured
-export const TEXT1 = 'login';
-export const MSG = 'welcome';
-export const DELETE_CONFIRM = 'delete_confirm';
-```
-
----
-
-## 🤔 Why Use i18n Keys
-
-### Problem: Pain Points of Hard-coded Text
-
-```typescript
-// ❌ Traditional approach: Hard-coded text
-
-function LoginPage() {
-  return (
-    <div>
-      <h1>Login</h1>
-      <button>Login</button>
-      <p>Welcome back!</p>
-      <span>Forgot password?</span>
-    </div>
-  );
-}
-
-// 😰 Problem 1: Difficult to internationalize
-// If we need to support Chinese, need to modify lots of code
-
-// 😰 Problem 2: Hard to maintain
-// Same text might be used in multiple places, easy to miss when changing
-
-// 😰 Problem 3: Hard to manage uniformly
-// Can't count how many texts exist in the project, which need translation
-
-// 😰 Problem 4: Hard to search
-// To find where a text is used, can only globally search strings
-```
-
-### Solution: Use i18n Keys
-
-```typescript
-// ✅ Use i18n Keys
-
-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>
-  );
-}
-
-// ✅ Advantage 1: Automatic internationalization
-// Automatically displays corresponding text based on user language
-
-// ✅ Advantage 2: Centralized management
-// All text managed uniformly in Identifier files
-
-// ✅ Advantage 3: Easy to maintain
-// Only need to modify in one place
-
-// ✅ Advantage 4: Type safe
-// TypeScript will check if Key exists
-
-// ✅ Advantage 5: Reduce thinking ⭐
-// Developers only need to know BUTTON_LOGIN is a variable
-// Don't need to remember 'common:button.login' string
-// IDE will provide auto-completion, wrong spelling will immediately error
-```
-
-### Comparison Summary
-
-| Feature                  | Hard-coded Text                    | i18n Key                             |
-| ------------------------ | ---------------------------------- | ------------------------------------ |
-| **Internationalization** | ❌ Difficult (need to change code) | ✅ Automatic (just switch language)  |
-| **Maintainability**      | ❌ Poor (scattered everywhere)     | ✅ Good (centralized management)     |
-| **Reusability**          | ❌ Poor (copy-paste)               | ✅ Good (reference Key)              |
-| **Searchability**        | ❌ Difficult (string search)       | ✅ Simple (search constant)          |
-| **Countability**         | ❌ Impossible                      | ✅ Easy (count Keys)                 |
-| **Type Safety**          | ❌ None                            | ✅ Yes (TypeScript)                  |
-| **Cognitive Burden**     | ❌ High (need to remember text)    | ✅ Low (just remember variable name) |
-| **IDE Support**          | ❌ No auto-complete                | ✅ Full auto-complete                |
-
-### ⭐ Core Advantage: Reduce Developer Thinking
-
-**The most important advantage: Developers don't need to care about what the actual i18n string is!**
-
-```typescript
-// ❌ Traditional approach: Need to remember complex strings
-function LoginPage() {
-  const { t } = useTranslation();
-
-  return (
-    <div>
-      {/* 😰 Need to remember 'common:button.login' */}
-      <button>{t('common:button.login')}</button>
-
-      {/* 😰 Need to remember 'page.login.title' */}
-      <h1>{t('page.login.title')}</h1>
-
-      {/* 😰 Spelling mistake won't error */}
-      <p>{t('page.login.welcom')}</p>  {/* welcom → welcome, spelling error */}
-    </div>
-  );
-}
-
-// ✅ i18n Key approach: Just need to know variable name
-import { BUTTON_LOGIN, PAGE_LOGIN_TITLE, PAGE_LOGIN_WELCOME } from '@config/Identifier';
-
-function LoginPage() {
-  const { t } = useAppTranslation();
-
-  return (
-    <div>
-      {/* ✅ Just remember BUTTON_LOGIN, IDE will auto-complete */}
-      <button>{t(BUTTON_LOGIN)}</button>
-
-      {/* ✅ Type PAGE_ and IDE will show all available Keys */}
-      <h1>{t(PAGE_LOGIN_TITLE)}</h1>
-
-      {/* ✅ Wrong spelling will immediately error in TypeScript */}
-      <p>{t(PAGE_LOGIN_WELCOM)}</p>  {/* ❌ TS error: Variable not found */}
-    </div>
-  );
-}
-```
-
-**Development Experience Comparison:**
-
-```typescript
-// ❌ Using strings workflow:
-// 1. 😰 Check translation files, find corresponding key
-// 2. 😰 Remember complete key path (like 'common:page.login.title')
-// 3. 😰 Manually type the string in code
-// 4. 😰 May type incorrectly, but compiler won't error
-// 5. 😰 Only discover translation didn't work at runtime
-
-// ✅ Using i18n Key workflow:
-// 1. 😊 Type variable name prefix (like BUTTON_)
-// 2. 😊 IDE automatically suggests all available Keys
-// 3. 😊 Select needed Key, IDE auto-completes
-// 4. 😊 If typed incorrectly, TypeScript immediately errors
-// 5. 😊 Can ensure Key correctness at compile time
-```
-
-**Cognitive Burden Comparison:**
-
-| What Developers Need to Remember | String Method                                 | i18n Key Method                |
-| -------------------------------- | --------------------------------------------- | ------------------------------ |
-| **Translation File Structure**   | ✅ Must remember (like `common:button.login`) | ❌ Don't need to               |
-| **Namespace**                    | ✅ Must remember (like `common:`, `page:`)    | ❌ Don't need to               |
-| **String Path**                  | ✅ Must remember complete path                | ❌ Don't need to               |
-| **Variable Name**                | ❌ No variable                                | ✅ Just remember variable name |
-| **IDE Hints**                    | ❌ None                                       | ✅ Full hints                  |
-
-**Real Development Scenarios:**
-
-```typescript
-// Scenario 1: Write a new button
-
-// ❌ String method (need to think a lot)
-// 1. What should this button's translation key be called?
-// 2. Which namespace should it go in? common? page?
-// 3. What should the path be? button.submit? submit.button?
-// 4. Finally write: t('common:button.submit')
-<button>{t('common:button.submit')}</button>
-
-// ✅ i18n Key method (just need to search)
-// 1. Type BUTTON_
-// 2. IDE shows all available button Keys
-// 3. See BUTTON_SUBMIT, select it
-// 4. Done!
-<button>{t(BUTTON_SUBMIT)}</button>
-
-// Scenario 2: Change text on another page
-
-// ❌ String method
-// 1. Check that page's code
-// 2. Find t('page.home.welcome')
-// 3. Remember this string
-// 4. Search and modify in translation files
-
-// ✅ i18n Key method
-// 1. See PAGE_HOME_WELCOME in code
-// 2. Jump directly to definition (IDE's Go to Definition)
-// 3. Modify translation in comment
-// 4. Automatically generate new translation files
-```
-
-**Summary:**
-
-Using i18n Keys allows developers to:
-
-- ✅ **Don't need to remember** complex string paths
-- ✅ **Don't need to remember** translation file structure
-- ✅ **Don't need to care about** specific translation key names
-- ✅ **Just need to know** this is a variable
-- ✅ **Rely on IDE** provided auto-complete and type checking
-- ✅ **Focus on** business logic, not translation details
-
-> 💡 **Core Philosophy: Let developers put their energy into business logic, not memorizing translation strings!**
-
----
-
-## 🛠️ Implementation in the Project
-
-### 1. File Structure
-
-```
-config/
-└── Identifier/           # i18n Key definition directory
-    ├── index.ts          # Export all Keys
-    ├── common/           # Common text
-    │   ├── index.ts
-    │   ├── common.ts     # General text (buttons, messages, etc.)
-    │   └── common.error.ts # Error messages
-    └── pages/            # Page text
-        ├── index.ts
-        ├── page.home.ts  # Home page text
-        ├── page.login.ts # Login page text
-        └── page.about.ts # About page text
-
-public/
-└── locales/              # Generated translation files
-    ├── zh/
-    │   └── common.json   # Chinese translations
-    └── en/
-        └── common.json   # English translations
-
-src/
-└── uikit/
-    └── hooks/
-        └── useAppTranslation.ts  # Translation Hook
-```
-
-### 2. i18n Configuration
-
-```typescript
-// config/i18n/i18nConfig.ts
-export const i18nConfig = {
-  fallbackLng: 'en', // Default language
-  debug: false,
-  interpolation: {
-    escapeValue: false
-  },
-  ns: ['common'], // Namespaces
-  defaultNS: 'common',
-  backend: {
-    loadPath: '/locales/{{lng}}/{{ns}}.json' // Translation file path
-  },
-  supportedLngs: ['en', 'zh'] // Supported languages
-} as const;
-```
-
-### 3. I18nService (Bootstrap Plugin)
-
-```typescript
-// src/base/services/I18nService.ts
-export class I18nService implements BootstrapExecutorPlugin {
-  readonly pluginName = 'I18nService';
-
-  constructor(protected pathname: string) {
-    super(() => new I18nServiceState(i18n.language));
-  }
-
-  /**
-   * Initialize i18n on Bootstrap startup
-   */
-  onBefore(): void {
-    i18n
-      .use(HttpApi) // Load translation files
-      .use(LanguageDetector) // Language detection
-      .use(initReactI18next) // React integration
-      .init(i18nConfig); // Initialize config
-
-    // Add custom language detector (detect from URL path)
-    const pathLanguageDetector = {
-      name: 'pathLanguageDetector',
-      lookup: () => {
-        const paths = this.pathname.split('/');
-        for (const path of paths) {
-          if (this.isValidLanguage(path)) {
-            return path; // Extract language from URL (like /zh/home)
-          }
-        }
-        return fallbackLng;
-      },
-      cacheUserLanguage(lng: string) {
-        localStorage.setItem('i18nextLng', lng);
-      }
-    };
-
-    i18n.services.languageDetector.addDetector(pathLanguageDetector);
-  }
-
-  /**
-   * Switch language
-   */
-  async changeLanguage(language: string): Promise<void> {
-    await i18n.changeLanguage(language);
-    localStorage.setItem('i18nextLng', language);
-  }
-
-  /**
-   * Translate text
-   */
-  t(key: string, params?: Record<string, unknown>): string {
-    return i18n.t(key, { lng: i18n.language, ...params });
-  }
-}
-```
-
-### 4. Auto-generate Translation Files
-
-```typescript
-// vite.config.ts
-import ts2Locales from '@brain-toolkit/ts2locales/vite';
-
-export default defineConfig({
-  plugins: [
-    // ✅ ts2locales plugin: Auto-generate translation files from TypeScript comments
-    ts2Locales({
-      locales: ['en', 'zh'],
-      options: generateTs2LocalesOptions() // Configure generation rules
-    })
-  ]
-});
-```
-
-**How it works:**
-
-```typescript
-// 1. Define Key in Identifier file
-/**
- * @description Login button text
- * @localZh 登录
- * @localEn Login
- */
-export const BUTTON_LOGIN = 'common:button.login';
-
-// 2. ts2locales plugin automatically generates translation files
-
-// public/locales/zh/common.json
-{
-  "button": {
-    "login": "登录"
-  }
-}
-
-// public/locales/en/common.json
-{
-  "button": {
-    "login": "Login"
-  }
-}
-```
-
----
-
-## 📝 How to Use
-
-### 1. Define 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';
-```
-
-**Comment conventions:**
-
-- `@description`: Explain text purpose (English)
-- `@localZh`: Chinese translation
-- `@localEn`: English translation
-
-### 2. Use in UI Components
-
-```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>
-      {/* ✅ Simple text */}
-      <h1>{t(PAGE_HOME_TITLE)}</h1>
-      <p>{t(PAGE_HOME_WELCOME)}</p>
-
-      {/* ✅ Text with parameters */}
-      <p>{t(PAGE_HOME_GREETING, { name: userName })}</p>
-    </div>
-  );
-}
-```
-
-### 3. Use in Services
-
-```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) {
-      // ✅ Use i18n in service
-      throw new Error(this.i18n.t(ERROR_USER_NOT_FOUND, { id }));
-    }
-
-    return user;
-  }
-}
-```
-
-### 4. Switch Language
-
-```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') => {
-    // ✅ Switch language
-    i18nService.changeLanguage(lang);
-  };
-
-  return (
-    <select value={currentLang} onChange={(e) => handleChange(e.target.value)}>
-      <option value="zh">中文</option>
-      <option value="en">English</option>
-    </select>
-  );
-}
-```
-
-### 5. Complex Scenarios
-
-#### Scenario 1: Dynamic Text
-
-```typescript
-/**
- * @description Upload progress message
- * @localZh 已上传 {{current}} / {{total}} 个文件
- * @localEn Uploaded {{current}} / {{total}} files
- */
-export const UPLOAD_PROGRESS = 'common:upload.progress';
-
-// Usage
-<p>{t(UPLOAD_PROGRESS, { current: 3, total: 10 })}</p>
-// Chinese: 已上传 3 / 10 个文件
-// English: Uploaded 3 / 10 files
-```
-
-#### Scenario 2: Plural Forms
-
-```typescript
-/**
- * @description Files count message
- * @localZh {{count}} 个文件
- * @localEn {{count}} file_plural
- */
-export const FILES_COUNT = 'common:files.count';
-
-// Usage
-<p>{t(FILES_COUNT, { count: 1 })}</p>  // 1 file
-<p>{t(FILES_COUNT, { count: 5 })}</p>  // 5 files
-```
-
-#### Scenario 3: HTML Content
-
-```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';
-
-// Usage (Need to use Trans component in React)
-import { Trans } from 'react-i18next';
-
-<Trans i18nKey={TERMS_AGREEMENT}>
-  I have read and agree to the <a href="/terms">Terms of Service</a>
-</Trans>
-```
-
----
-
-## 💎 Best Practices
-
-### 1. ✅ All Text Uses i18n Keys
-
-```typescript
-// ❌ Wrong: Mix hard-coded and i18n Keys
-function LoginForm() {
-  return (
-    <form>
-      <h1>{t(PAGE_LOGIN_TITLE)}</h1>
-      <button>Login</button>  {/* ❌ Hard-coded */}
-      <a href="/forgot">Forgot password?</a>  {/* ❌ Hard-coded */}
-    </form>
-  );
-}
-
-// ✅ Correct: All text uses i18n Keys
-function LoginForm() {
-  return (
-    <form>
-      <h1>{t(PAGE_LOGIN_TITLE)}</h1>
-      <button>{t(BUTTON_LOGIN)}</button>  {/* ✅ Use Key */}
-      <a href="/forgot">{t(LINK_FORGOT_PASSWORD)}</a>  {/* ✅ Use Key */}
-    </form>
-  );
-}
-```
-
-### 2. ✅ Organize i18n Keys Reasonably
-
-```typescript
-// ✅ Good organization: Categorize by functional modules
-config/Identifier/
-├── common/
-│   ├── common.ts           # General text (buttons, labels, etc.)
-│   └── common.error.ts     # Error messages
-├── pages/
-│   ├── page.home.ts        # Home page text
-│   ├── page.login.ts       # Login page text
-│   └── page.about.ts       # About page text
-└── components/
-    ├── component.header.ts # Header component text
-    └── component.footer.ts # Footer component text
-```
-
-### 3. ✅ Use Semantic Naming
-
-```typescript
-// ✅ Good naming: Clearly expresses meaning
-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';
-
-// ❌ Bad naming: Unclear meaning
-export const BTN1 = 'btn1';
-export const TEXT = 'text';
-export const MSG = 'msg';
-```
-
-### 4. ✅ Add Clear Comments to i18n Keys
-
-```typescript
-// ✅ Good comments: Clearly explain purpose and context
-/**
- * @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';
-
-// ❌ Bad comments: No context information
-/**
- * @description Delete
- * @localZh 删除
- * @localEn Delete
- */
-export const DELETE = 'delete';
-```
-
-### 5. ✅ Unified Naming Conventions
-
-```typescript
-// ✅ Recommended naming conventions:
-
-// Button text
-export const BUTTON_LOGIN = 'common:button.login';
-export const BUTTON_SUBMIT = 'common:button.submit';
-export const BUTTON_CANCEL = 'common:button.cancel';
-
-// Page titles
-export const PAGE_HOME_TITLE = 'common:page.home.title';
-export const PAGE_ABOUT_TITLE = 'common:page.about.title';
-
-// Error messages
-export const ERROR_NETWORK = 'common:error.network';
-export const ERROR_INVALID_INPUT = 'common:error.invalid.input';
-
-// Message prompts
-export const MESSAGE_SUCCESS = 'common:message.success';
-export const MESSAGE_WARNING = 'common:message.warning';
-
-// Confirm dialogs
-export const CONFIRM_DELETE = 'common:confirm.delete';
-export const CONFIRM_LOGOUT = 'common:confirm.logout';
-
-// Link text
-export const LINK_FORGOT_PASSWORD = 'common:link.forgot.password';
-export const LINK_PRIVACY_POLICY = 'common:link.privacy.policy';
-```
-
-### 6. ✅ Avoid Duplicate Definitions
-
-```typescript
-// ❌ Wrong: Duplicate definitions of same text
-// 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';
-
-// ✅ Correct: Define once in common file, reference in multiple places
-// config/Identifier/common/common.ts
-export const BUTTON_OK = 'common:button.ok';
-
-// Reference in various pages
-import { BUTTON_OK } from '@config/Identifier';
-```
-
-### 7. ✅ Use Parameterized Text
-
-```typescript
-// ❌ Bad: Define different Keys for each case
-export const WELCOME_USER_JOHN = 'common:welcome.john';
-export const WELCOME_USER_MARY = 'common:welcome.mary';
-
-// ✅ Good: Use parameters
-/**
- * @description Welcome message with user name
- * @localZh 欢迎，{{name}}！
- * @localEn Welcome, {{name}}!
- */
-export const WELCOME_USER = 'common:welcome.user';
-
-// Usage
-<h1>{t(WELCOME_USER, { name: 'John' })}</h1>
-<h1>{t(WELCOME_USER, { name: 'Mary' })}</h1>
-```
-
----
-
-## ❓ FAQ
-
-### Q1: Why can't I write text directly?
-
-**A:**
-
-```typescript
-// ❌ Problems with writing text directly
-<button>Login</button>
-
-// Problem 1: Cannot internationalize
-// If user switches to Chinese, text won't change
-
-// Problem 2: Hard to maintain
-// If want to change "Login" to "Sign In", need to find all places to modify
-
-// Problem 3: Cannot manage uniformly
-// Can't know how many "Login" buttons exist in the project
-
-// ✅ Advantages of using i18n Key
-<button>{t(BUTTON_LOGIN)}</button>
-
-// ✅ Automatic internationalization: Switch language to automatically show corresponding text
-// ✅ Easy to maintain: Only need to modify definition in one place
-// ✅ Unified management: All text centralized in Identifier files
-```
-
-### Q2: How to know where a Key is used?
-
-**A:**
-
-```bash
-# Search constant name
-grep -r "BUTTON_LOGIN" src/
-
-# Or use "Find Usages" feature in IDE
-# Can quickly find all places using this Key
-```
-
-### Q3: What if I forget to define an i18n Key?
-
-**A:** TypeScript will error at compile time:
-
-```typescript
-// ❌ Using undefined Key
-<button>{t(BUTTON_NOT_EXIST)}</button>
-// TypeScript error: Cannot find name 'BUTTON_NOT_EXIST'
-
-// ✅ Correct: Define Key first
-export const BUTTON_NOT_EXIST = 'common:button.not.exist';
-```
-
-### Q4: How to handle dynamic text?
-
-**A:** Use parameters:
-
-```typescript
-/**
- * @description User greeting with name and time
- * @localZh {{name}}，{{time}}好！
- * @localEn Good {{time}}, {{name}}!
- */
-export const GREETING_WITH_TIME = 'common:greeting.with.time';
-
-// Usage
-<h1>{t(GREETING_WITH_TIME, { name: 'John', time: 'morning' })}</h1>
-// Chinese: John，morning好！
-// English: Good morning, John!
-```
-
-### Q5: How are translation files generated?
-
-**A:**
-
-```
-1. Developer defines Keys and translation comments in Identifier files
-   ↓
-2. ts2locales plugin scans TypeScript files
-   ↓
-3. Extract @localZh and @localEn from comments
-   ↓
-4. Auto-generate public/locales/{lng}/common.json
-   ↓
-5. i18next loads these JSON files at runtime
-```
-
-### Q6: Can I use translated text directly in code?
-
-**A:**
-
-```typescript
-// ❌ Not recommended: Skip i18n system
-const loginText = 'Login';  // Hard-coded
-<button>{loginText}</button>
-
-// ✅ Recommended: Always use i18n Key
-const loginText = t(BUTTON_LOGIN);  // Through i18n system
-<button>{loginText}</button>
-```
-
-### Q7: How to test 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');
-  });
-});
-```
-
----
-
-## 📚 Related Documentation
-
-- [Project Architecture Design](./index.md) - Understand overall architecture
-- [Bootstrap Initializer](./bootstrap.md) - I18nService is one of the Bootstrap plugins
-- [Configuration-Driven Development](./#configuration-driven-development) - i18n Key is a practice of configuration-driven development
-
----
-
-## 🎉 Summary
-
-Core philosophy of the internationalization system:
-
-1. **Unique Identifier** 🔑 - Every text has a unique i18n Key
-2. **Never Hard-code** 🚫 - All text in project must use i18n Keys
-3. **Reduce Thinking** 🧠 - Developers only need to know variable names, don't need to remember string paths
-4. **Centralized Management** 📦 - All Key definitions in Identifier directory
-5. **Auto-generation** ⚡ - Translation files auto-generated from comments
-6. **Type Safety** 🔒 - TypeScript provides complete type checking
-7. **Easy to Maintain** 🛠️ - Only need to modify translation in one place
-8. **IDE Friendly** 💻 - Complete auto-completion and type hints
-
-**Remember two core principles:**
-
-1. **Never write text directly in code!**
-2. **Developers don't need to remember translation strings, just variable names!**
-
-```typescript
-// ❌ Never do this
-<button>Login</button>
-<h1>Welcome back</h1>
-<p>{t('common:confirm.delete')}</p>  // Don't write strings directly either
-
-// ✅ Always do this
-<button>{t(BUTTON_LOGIN)}</button>
-<h1>{t(MESSAGE_WELCOME)}</h1>
-<p>{t(CONFIRM_DELETE)}</p>  // Use variables, IDE will auto-complete
-```
-
-**Development Workflow:**
-
-```typescript
-// 1. Type variable name prefix
-t(BUTTON_
-
-// 2. IDE automatically suggests all available Keys
-// BUTTON_LOGIN
-// BUTTON_SUBMIT
-// BUTTON_CANCEL
-// ...
-
-// 3. Select needed Key, done!
-t(BUTTON_LOGIN)
-
-// Don't need to remember 'common:button.login'
-// Don't need to care about translation file structure
-// Don't need to worry about spelling errors (TypeScript will check)
-```
-
----
-
-**Feedback:**  
-If you have any questions or suggestions about the internationalization system, please discuss in the team channel or submit an Issue.