@qlover/create-app 0.7.15 → 0.9.0

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

@@ -1,152 +1,568 @@
-# Internationalization System
+# Internationalization (i18n)
 
-## Overview
+## 📋 Table of Contents
 
-The internationalization system adopts an identifier-alias based approach, combining i18next and TypeScript comments to implement a type-safe, maintainable internationalization solution. Main features:
+- [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
 
-- **Identifier Aliases**: Use constants instead of strings as translation keys
-- **TypeScript Comments**: Automatically generate translation resources through comments
-- **Type Safety**: Complete type checking and auto-completion
-- **Router Integration**: Support language parameters in URL paths
-- **Auto Generation**: Automatically generate translation files from source code
-- **Developer Friendly**: Complete development tool support
+---
 
-## Core Concepts
+## 🎯 Core Philosophy
 
-### 1. Identifier Aliases
+> **🚨 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!**
 
-Use constants instead of string keys to provide better type safety and maintainability:
+> **⭐ 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
-// config/Identifier/common.ts
+// ❌ 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 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';
+//            ↑ Constant name            ↑ Identifier string
+//            Used in code               Key name stored in translation files
 
 /**
- * @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. Auto Generation Configuration
+**Structure explanation:**
+
+```
+'common:button.login'
+   ↑      ↑      ↑
+Namespace Category Specific identifier
+```
 
-Configure auto generation in `vite.config.ts`:
+### Naming Conventions
 
 ```typescript
-import ts2Locales from '@brain-toolkit/ts2locales/vite';
+// ✅ 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';
+```
 
-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'
-        }
-      ]
-    })
-  ]
-});
+---
+
+## 🤔 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
 ```
 
-### 3. i18n Service Configuration
+### 2. i18n Configuration
 
 ```typescript
-// config/i18n.ts
-export default {
-  fallbackLng: 'en',
+// config/i18n/i18nConfig.ts
+export const i18nConfig = {
+  fallbackLng: 'en', // Default language
   debug: false,
   interpolation: {
     escapeValue: false
   },
-  ns: ['common'],
+  ns: ['common'], // Namespaces
   defaultNS: 'common',
   backend: {
-    loadPath: '/locales/{{lng}}/{{ns}}.json'
+    loadPath: '/locales/{{lng}}/{{ns}}.json' // Translation file path
   },
-  supportedLngs: ['en', 'zh']
+  supportedLngs: ['en', 'zh'] // Supported languages
 } as const;
 ```
 
-## Usage
+### 3. I18nService (Bootstrap Plugin)
 
-### 1. Define Translation Keys
+```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
-// config/Identifier/page.ts
+// 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 = '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. Using in Components
+**Comment conventions:**
+
+- `@description`: Explain text purpose (English)
+- `@localZh`: Chinese translation
+- `@localEn`: English translation
 
-```tsx
-import { useTranslation } from 'react-i18next';
-import * as i18nKeys from '@config/Identifier/page';
+### 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 } = useTranslation();
+  const { t } = useAppTranslation();
+  const userName = 'John';
 
   return (
     <div>
-      <h1>{t(i18nKeys.PAGE_HOME_TITLE)}</h1>
-      <p>{t(i18nKeys.PAGE_HOME_WELCOME)}</p>
+      {/* ✅ 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. Translations with Parameters
+### 3. Use in Services
 
 ```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) {
+      // ✅ Use i18n in service
+      throw new Error(this.i18n.t(ERROR_USER_NOT_FOUND, { id }));
+    }
+
+    return user;
+  }
 }
 ```
 
-### 4. Language Switching
+### 4. Switch Language
 
-```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') => {
+    // ✅ Switch language
     i18nService.changeLanguage(lang);
   };
 
@@ -159,110 +575,405 @@ function LanguageSwitcher() {
 }
 ```
 
-## Best Practices
+### 5. Complex Scenarios
 
-### 1. Identifier Organization
+#### Scenario 1: Dynamic Text
 
-- **Naming Conventions**:
+```typescript
+/**
+ * @description Upload progress message
+ * @localZh 已上传 {{current}} / {{total}} 个文件
+ * @localEn Uploaded {{current}} / {{total}} files
+ */
+export const UPLOAD_PROGRESS = 'common:upload.progress';
 
-  ```typescript
-  // Page related
-  PAGE_HOME_TITLE;
-  PAGE_ABOUT_DESCRIPTION;
+// Usage
+<p>{t(UPLOAD_PROGRESS, { current: 3, total: 10 })}</p>
+// Chinese: 已上传 3 / 10 个文件
+// English: Uploaded 3 / 10 files
+```
 
-  // Feature module related
-  AUTH_LOGIN_BUTTON;
-  AUTH_LOGOUT_CONFIRM;
+#### Scenario 2: Plural Forms
 
-  // Common component related
-  COMMON_SUBMIT_BUTTON;
-  COMMON_CANCEL_BUTTON;
-  ```
+```typescript
+/**
+ * @description Files count message
+ * @localZh {{count}} 个文件
+ * @localEn {{count}} file_plural
+ */
+export const FILES_COUNT = 'common:files.count';
 
-- **File Organization**:
-  ```
-  config/
-  ├── Identifier/
-  │   ├── common.ts     // Common text
-  │   ├── page.ts       // Page text
-  │   ├── error.ts      // Error messages
-  │   └── auth.ts       // Authentication related
-  ```
+// Usage
+<p>{t(FILES_COUNT, { count: 1 })}</p>  // 1 file
+<p>{t(FILES_COUNT, { count: 5 })}</p>  // 5 files
+```
 
-### 2. Comment Standards
+#### Scenario 3: HTML Content
 
 ```typescript
 /**
- * @description Brief description explaining text usage
- * @localZh Chinese translation text
- * @localEn English translation text
+ * @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>
+  );
+}
 ```
 
-### 3. Type Safety
+### 2. ✅ Organize i18n Keys Reasonably
 
 ```typescript
-// Use type imports to ensure key existence
-import * as i18nKeys from '@config/Identifier';
+// ✅ 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
 
-// Type checking catches incorrect keys
-t(i18nKeys.NONEXISTENT_KEY); // TS error
+```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. Dynamic Content
+### 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 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. ✅ 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
-t(i18nKeys.UPLOAD_PROGRESS, { count: 3, total: 10 });
+<h1>{t(WELCOME_USER, { name: 'John' })}</h1>
+<h1>{t(WELCOME_USER, { name: 'Mary' })}</h1>
 ```
 
-## Workflow
+---
 
-1. **Development Phase**:
-   - Define translation keys and comments in Identifier files
-   - Reference translations using identifier aliases in code
-   - Automatically generate translation files during development server runtime
+## ❓ FAQ
 
-2. **Build Phase**:
-   - Automatically check translation completeness
-   - Generate production translation files
-   - Optimize translation resource loading
+### Q1: Why can't I write text directly?
 
-3. **Runtime**:
-   - Detect language based on URL
-   - Load translation resources on demand
-   - Respond to language switch events
+**A:**
 
-## Common Issues
+```typescript
+// ❌ Problems with writing text directly
+<button>Login</button>
 
-### 1. Translations Not Working
+// Problem 1: Cannot internationalize
+// If user switches to Chinese, text won't change
 
-Check the following:
+// Problem 2: Hard to maintain
+// If want to change "Login" to "Sign In", need to find all places to modify
 
-- Ensure identifiers are correctly exported
-- Check if comment format is correct
-- Verify translation files are generated
-- Confirm language detection is working
+// Problem 3: Cannot manage uniformly
+// Can't know how many "Login" buttons exist in the project
 
-### 2. Type Errors
+// ✅ Advantages of using i18n Key
+<button>{t(BUTTON_LOGIN)}</button>
 
-Possible solutions:
+// ✅ 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/
 
-- Check identifier import paths
-- Ensure correct identifier usage
-- Update TypeScript type definitions
+# 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?
 
-### 3. Performance Optimization
+**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)
+```
 
-Development suggestions:
+---
 
-- Reasonably split translation files
-- Use translation resource preloading
-- Avoid duplicate translation keys
+**Feedback:**  
+If you have any questions or suggestions about the internationalization system, please discuss in the team channel or submit an Issue.