DOAS/docs/i18n-guide.md

# 多语言配置使用指南

## 概述

本项目已集成 Vue I18n 国际化支持，支持中文和英文两种语言。系统会根据用户浏览器语言自动选择默认语言，用户也可以手动切换语言。

## 主要特性

- ✅ 支持中文（zh）、英文（en）和日文（ja）
- ✅ 自动检测浏览器语言
- ✅ Cookie 持久化语言选择
- ✅ Element UI 组件多语言支持
- ✅ Vuex 状态管理
- ✅ 语言切换组件

## 目录结构

```
src/
├── i18n/
│   ├── index.js          # i18n 主配置文件
│   └── lang/
│       ├── zh.js         # 中文语言包
│       ├── en.js         # 英文语言包
│       └── ja.js         # 日文语言包
├── components/
│   └── LangSelect/       # 语言切换组件
│       └── index.vue
└── store/
    └── modules/
        └── language.js   # 语言状态管理
```

## 基础使用

### 1. 模板中使用

```vue
<template>
  <div>
    <!-- 基础翻译 -->
    <h1>{{ $t('system.title') }}</h1>
    
    <!-- 按钮文本 -->
    <el-button>{{ $t('button.save') }}</el-button>
    
    <!-- 属性中使用 -->
    <el-input :placeholder="$t('form.username')"></el-input>
    
    <!-- 带参数的翻译 -->
    <span>{{ $t('pagination.total', { total: 100 }) }}</span>
  </div>
</template>
```

### 2. JavaScript 中使用

```javascript
export default {
  methods: {
    showMessage() {
      // 显示国际化消息
      this.$message.success(this.$t('message.success'))
    },
    
    // 表单验证规则中使用
    getValidationRules() {
      return {
        username: [
          { 
            required: true, 
            message: this.$t('message.inputRequired'), 
            trigger: 'blur' 
          }
        ]
      }
    }
  }
}
```

### 3. 语言切换组件

```vue
<template>
  <div>
    <!-- 在导航栏或任何位置添加语言切换器 -->
    <lang-select></lang-select>
  </div>
</template>
```

## 语言包结构

### 中文语言包 (src/i18n/lang/zh.js)

```javascript
export default {
  // 系统通用
  system: {
    title: '数字化办公自动化系统',
    name: 'DOAS',
    welcome: '欢迎使用'
  },
  
  // 通用按钮  
  button: {
    search: '搜索',
    reset: '重置',
    add: '新增',
    save: '保存'
  },
  
  // 表单标签
  form: {
    username: '用户名',
    password: '密码',
    email: '邮箱'
  }
}
```

### 英文语言包 (src/i18n/lang/en.js)

```javascript
export default {
  // System common
  system: {
    title: 'Digital Office Automation System',
    name: 'DOAS',
    welcome: 'Welcome to'
  },
  
  // Common buttons
  button: {
    search: 'Search',
    reset: 'Reset',
    add: 'Add',
    save: 'Save'
  },
  
  // Form labels
  form: {
    username: 'Username',
    password: 'Password',
    email: 'Email'
  }
}
```

### 日文语言包 (src/i18n/lang/ja.js)

```javascript
export default {
  // システム共通
  system: {
    title: 'デジタルオフィス自動化システム',
    name: 'DOAS',
    welcome: 'ようこそ'
  },
  
  // 共通ボタン
  button: {
    search: '検索',
    reset: 'リセット',
    add: '追加',
    save: '保存'
  },
  
  // フォームラベル
  form: {
    username: 'ユーザー名',
    password: 'パスワード',
    email: 'メールアドレス'
  }
}
```

## 高级用法

### 1. 动态语言切换

```javascript
// 在组件中切换语言
this.$i18n.locale = 'ja' // 或 'zh', 'en'
this.$store.dispatch('language/setLanguage', 'ja')
```

### 2. 条件翻译

```vue
<template>
  <div>
    <span v-if="$i18n.locale === 'zh'">中文特有内容</span>
    <span v-else>English specific content</span>
  </div>
</template>
```

### 3. 复数形式处理

```javascript
// 语言包中定义
{
  message: {
    apple: 'no apples | one apple | {count} apples'
  }
}

// 使用
{{ $tc('message.apple', count) }}
```

## 开发指南

### 1. 添加新的翻译

1. 在 `src/i18n/lang/zh.js` 中添加中文翻译
2. 在 `src/i18n/lang/en.js` 中添加对应的英文翻译
3. 确保两个语言包的 key 保持一致

### 2. 最佳实践

#### 命名规范
- 使用有意义的嵌套结构
- 按功能模块组织翻译 key
- 避免过深的嵌套层级（建议不超过 3 层）

```javascript
// ✅ 推荐
{
  user: {
    profile: {
      name: '姓名',
      email: '邮箱'
    }
  }
}

// ❌ 不推荐
{
  userProfileFormFieldLabelName: '姓名'
}
```

#### 参数化翻译
```javascript
// 语言包
{
  welcome: '欢迎 {name}，您有 {count} 条新消息'
}

// 使用
{{ $t('welcome', { name: userName, count: messageCount }) }}
```

### 3. 测试多语言

建议在开发过程中：
1. 经常切换语言测试界面显示
2. 检查所有文本是否正确翻译
3. 确保不同语言下的布局不会破坏

## 扩展支持新语言

系统目前支持中文、英文、日文三种语言。如需添加其他新语言（如韩语），按以下步骤：

1. 创建语言包文件 `src/i18n/lang/ko.js`
2. 在 `src/i18n/index.js` 中导入并配置
3. 更新语言选择组件支持新语言
4. 导入对应的 Element UI 语言包

```javascript
// src/i18n/index.js
import koLocale from './lang/ko'
import elementKoLocale from 'element-ui/lib/locale/lang/ko'

const messages = {
  // ...existing languages
  ko: {
    ...koLocale,
    ...elementKoLocale
  }
}
```

## 注意事项

1. **性能考虑**：大型应用建议按需加载语言包
2. **SEO 优化**：考虑使用不同的路由前缀区分语言版本
3. **日期时间**：使用 moment.js 或 dayjs 处理不同语言的日期格式
4. **数字格式**：注意不同地区的数字、货币格式差异

## 常见问题

### Q: 切换语言后页面没有立即更新？
A: 确保使用了响应式的 `$t()` 函数，避免在 `data()` 中缓存翻译结果。

### Q: Element UI 组件的文本没有翻译？
A: 检查是否正确配置了 Element UI 的 i18n 选项。

### Q: 如何处理长文本翻译？
A: 建议将长文本放在单独的文件中，或者使用富文本编辑器。

## 参与贡献

如需添加新的翻译或改进现有翻译，请：
1. Fork 项目仓库
2. 创建功能分支
3. 添加或修改翻译文件
4. 提交 Pull Request

---

更多信息请参考 [Vue I18n 官方文档](https://vue-i18n.intlify.dev/)