intelligent-etmf-system-applet/CHANGELOG_I18N.md

国际化目录结构变更日志

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. 导入方式

   // 旧方式
   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. 导出结构

   // 旧方式
   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 模块）

# 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
  }
}

添加新语言（如日语）

# 为每个现有模块添加日语文件
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. 同步维护：确保同一模块下所有语言文件的键结构完全相同

相关链接

• 目录结构详细说明
• 语言包管理文档
• 国际化完整指南

---

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