# 国际化目录结构变更日志

## 2025-12-01 - 目录结构重组

### 变更说明

将语言包组织方式从**按语言分组**调整为**按功能模块分组**，以提升可维护性和扩展性。

### 变更前后对比

#### 旧结构（按语言分组）
```
locales/
├── zh-CN/
│   ├── common.js
│   ├── home.js
│   └── index.js
├── en-US/
│   ├── common.js
│   ├── home.js
│   └── index.js
└── index.js
```

#### 新结构（按功能模块分组）
```
locales/
├── common/
│   ├── zh_CN.js
│   └── en_US.js
├── pages/
│   └── home/
│       ├── zh_CN.js
│       └── en_US.js
├── index.js
├── README.md
└── STRUCTURE.md
```

### 主要变更

1. **目录组织**
   - ✅ 每个功能模块独立成目录
   - ✅ 同一模块的不同语言文件放在一起
   - ✅ 文件命名从 `zh-CN` 改为 `zh_CN`（使用下划线）

2. **导入方式**
   ```javascript
   // 旧方式
   import zhCN from './zh-CN'
   import enUS from './en-US'
   
   // 新方式
   import commonZhCN from './common/zh_CN'
   import commonEnUS from './common/en_US'
   import homeZhCN from './pages/home/zh_CN'
   import homeEnUS from './pages/home/en_US'
   ```

3. **导出结构**
   ```javascript
   // 旧方式
   export const messages = {
     'zh-CN': zhCN,
     'en-US': enUS
   }
   
   // 新方式
   export const messages = {
     'zh-CN': {
       common: commonZhCN,
       home: homeZhCN
     },
     'en-US': {
       common: commonEnUS,
       home: homeEnUS
     }
   }
   ```

### 新结构的优势

1. **更易维护**
   - 同一模块的不同语言翻译在同一目录下
   - 可以同时打开对比编辑，确保键的一致性
   - 便于发现翻译遗漏或不一致

2. **更易扩展**
   - 添加新语言：只需在每个模块目录下添加新文件
   - 添加新模块：创建新目录，包含所有语言文件
   - 不需要维护多个语言目录的平行结构

3. **更清晰的职责**
   - 每个模块独立管理自己的翻译
   - 模块化开发更友好
   - 减少目录层级，结构更扁平

4. **团队协作更友好**
   - 减少文件冲突（不同模块在不同目录）
   - 代码审查更容易（对比同目录下的文件）
   - 新成员更容易理解结构

### 迁移影响

#### 对现有代码的影响

**无影响** - 以下部分保持不变：

- ✅ 组件中的使用方式（`t('home.title')`）
- ✅ i18n 配置和初始化
- ✅ store 的使用方式
- ✅ API 接口（`useI18n`、`useLocaleStore`）

#### 需要更新的部分

- ✅ `locales/index.js` - 已更新导入和导出逻辑
- ✅ 相关文档 - 已更新所有示例和说明
- ✅ 旧文件 - 已删除

### 文档更新

已更新以下文档以反映新结构：

- ✅ `I18N_GUIDE.md` - 国际化完整指南
- ✅ `locales/README.md` - 语言包管理文档
- ✅ `locales/STRUCTURE.md` - 目录结构说明（新增）
- ✅ `i18n/README.md` - i18n 使用文档

### 快速上手

#### 添加新模块（如 user 模块）

```bash
# 1. 创建目录和文件
mkdir -p locales/pages/user
touch locales/pages/user/zh_CN.js
touch locales/pages/user/en_US.js

# 2. 编写翻译内容（略）

# 3. 在 locales/index.js 中注册
# 导入
import userZhCN from './pages/user/zh_CN'
import userEnUS from './pages/user/en_US'

# 注册
export const messages = {
  'zh-CN': {
    // ...
    user: userZhCN
  },
  'en-US': {
    // ...
    user: userEnUS
  }
}
```

#### 添加新语言（如日语）

```bash
# 为每个现有模块添加日语文件
touch locales/common/ja_JP.js
touch locales/pages/home/ja_JP.js

# 在 locales/index.js 中注册（参考文档）
```

### 注意事项

1. **文件命名**：使用下划线 `zh_CN.js`，不是连字符 `zh-CN.js`
2. **模块键名**：在 `locales/index.js` 中注册时，键名要与翻译键的第一级保持一致
3. **同步维护**：确保同一模块下所有语言文件的键结构完全相同

### 相关链接

- [目录结构详细说明](./locales/STRUCTURE.md)
- [语言包管理文档](./locales/README.md)
- [国际化完整指南](./I18N_GUIDE.md)

---

**变更日期**：2025-12-01  
**变更类型**：目录结构重组  
**向后兼容**：是（对使用方无影响）