# 国际化使用指南

## 目录结构

```
├── i18n/                   # i18n 配置目录
│   ├── index.js           # i18n 初始化配置
│   └── README.md          # 使用文档
├── locales/               # 语言包目录（按模块分组）
│   ├── common/           # 通用模块
│   │   ├── zh_CN.js     # 中文翻译
│   │   └── en_US.js     # 英文翻译
│   ├── pages/            # 页面模块
│   │   └── home/        # 首页模块
│   │       ├── zh_CN.js # 中文翻译
│   │       └── en_US.js # 英文翻译
│   ├── index.js          # 语言包导出
│   └── README.md         # 语言包管理文档
├── store/                 # 状态管理
│   └── locale.js         # 语言切换 store
└── components/            # 组件
    └── LanguageSwitcher/ # 语言切换组件
```

## 快速开始

### 1. 在页面中使用

```vue
<template>
  <view>
    <!-- 使用 t 函数翻译 -->
    <text>{{ t('home.title') }}</text>
    
    <!-- 使用嵌套的翻译键 -->
    <text>{{ t('common.button.confirm') }}</text>
  </view>
</template>

<script setup>
import { useI18n } from 'vue-i18n'

const { t } = useI18n()
</script>
```

### 2. 在 JS 中使用

```javascript
import { useI18n } from 'vue-i18n'

const { t } = useI18n()

// 使用翻译
const message = t('common.message.success')

// 使用参数
const greeting = t('common.greeting', { name: '张三' })
```

### 3. 切换语言

```vue
<script setup>
import { useLocaleStore } from '@/store/locale'

const localeStore = useLocaleStore()

// 切换到指定语言
localeStore.setLocale('en-US')

// 切换到下一个语言
localeStore.toggleLocale()

// 获取当前语言
const currentLang = localeStore.currentLocale
</script>
```

### 4. 使用语言切换组件

```vue
<template>
  <view>
    <!-- 直接使用组件 -->
    <LanguageSwitcher />
  </view>
</template>

<script setup>
import LanguageSwitcher from '@/components/LanguageSwitcher/index.vue'
</script>
```

## 添加新的语言模块

### 1. 创建新模块文件

在对应目录下创建语言文件：

```javascript
// locales/pages/user/zh_CN.js
export default {
  profile: '个人资料',
  settings: '设置',
  logout: '退出登录'
}
```

```javascript
// locales/pages/user/en_US.js
export default {
  profile: 'Profile',
  settings: 'Settings',
  logout: 'Logout'
}
```

### 2. 在索引文件中导入

```javascript
// locales/index.js
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'
import userZhCN from './pages/user/zh_CN'  // 新增
import userEnUS from './pages/user/en_US'  // 新增

export const messages = {
  'zh-CN': {
    common: commonZhCN,
    home: homeZhCN,
    user: userZhCN  // 新增
  },
  'en-US': {
    common: commonEnUS,
    home: homeEnUS,
    user: userEnUS  // 新增
  }
}
```

### 3. 在页面中使用

```vue
<template>
  <text>{{ t('user.profile') }}</text>
</template>
```

## 添加新的语言

### 1. 创建新语言文件

为每个现有模块添加新语言翻译：

```
locales/
  ├── common/
  │   ├── zh_CN.js
  │   ├── en_US.js
  │   └── ja_JP.js        # 新增日文
  └── pages/
      └── home/
          ├── zh_CN.js
          ├── en_US.js
          └── ja_JP.js    # 新增日文
```

### 2. 更新语言配置

```javascript
// locales/index.js
import commonZhCN from './common/zh_CN'
import commonEnUS from './common/en_US'
import commonJaJP from './common/ja_JP'  // 新增

import homeZhCN from './pages/home/zh_CN'
import homeEnUS from './pages/home/en_US'
import homeJaJP from './pages/home/ja_JP'  // 新增

export const messages = {
  'zh-CN': {
    common: commonZhCN,
    home: homeZhCN
  },
  'en-US': {
    common: commonEnUS,
    home: homeEnUS
  },
  'ja-JP': {  // 新增
    common: commonJaJP,
    home: homeJaJP
  }
}

export const localeList = [
  { label: '简体中文', value: 'zh-CN' },
  { label: 'English', value: 'en-US' },
  { label: '日本語', value: 'ja-JP' }  // 新增
]
```

## 最佳实践

### 1. 命名规范

- 使用小驼峰命名法：`userName`、`submitButton`
- 使用有意义的名称，避免使用 `text1`、`label2` 等
- 保持中英文翻译键一致

### 2. 模块划分

- 按功能模块划分：`common`、`home`、`user`、`order` 等
- `common` 模块存放通用文本：按钮、提示信息等
- 每个页面或功能一个独立模块

### 3. 翻译键结构

```javascript
// ✅ 推荐
{
  user: {
    profile: {
      title: '个人资料',
      name: '姓名',
      email: '邮箱'
    }
  }
}

// ❌ 不推荐
{
  userProfileTitle: '个人资料',
  userProfileName: '姓名',
  userProfileEmail: '邮箱'
}
```

### 4. 带参数的翻译

```javascript
// locales/zh-CN/common.js
export default {
  greeting: '你好，{name}！',
  itemCount: '共 {count} 项'
}

// 使用
t('common.greeting', { name: '张三' })
t('common.itemCount', { count: 10 })
```

## API 文档

### useLocaleStore

```javascript
const localeStore = useLocaleStore()

// 属性
localeStore.currentLocale        // 当前语言
localeStore.availableLocales     // 可用语言列表

// 方法
localeStore.initLocale()         // 初始化语言设置
localeStore.setLocale(locale)    // 设置语言
localeStore.toggleLocale()       // 切换到下一个语言
localeStore.getCurrentLocaleName() // 获取当前语言名称
```

### useI18n

```javascript
const { t, locale } = useI18n()

// 翻译文本
t('home.title')
t('common.greeting', { name: 'John' })

// 获取当前语言
console.log(locale.value)
```

## 注意事项

1. **uni-app 兼容性**：确保使用的 i18n 特性在小程序环境中可用
2. **性能优化**：语言包会在应用启动时全部加载，注意控制大小
3. **持久化**：语言设置会自动保存到本地存储
4. **SSR 支持**：使用 `createSSRApp` 时需要特别配置（已完成）

## 故障排查

### 问题：翻译不生效

检查：
1. 是否正确导入了模块
2. 翻译键是否正确
3. i18n 是否正确注册

### 问题：语言切换后部分文本未更新

原因：可能使用了非响应式的方式获取翻译
解决：确保使用 `t()` 函数或 `computed` 包装

### 问题：小程序中报错

检查：
1. 确保使用 `legacy: false` 配置
2. 确保正确配置了 `globalInjection`