228 lines
5.5 KiB
Markdown
228 lines
5.5 KiB
Markdown
# 国际化
|
|
|
|
<!-- Copyright (c) 2021-2026 小蚂蚁云团队 版权所有 -->
|
|
|
|
:::tip 说明
|
|
当前项目仅支持中文界面，Ant Design Vue 默认支持中文，所有界面文本直接硬编码在组件中。如需扩展多语言支持，可基于 vue-i18n 实现。
|
|
:::
|
|
|
|
## 当前状态
|
|
|
|
项目当前为中文单语言版本：
|
|
|
|
- Ant Design Vue 默认支持中文，无需额外配置语言包
|
|
- 所有界面文本直接硬编码在组件中：`<a-button>添加岗位</a-button>`
|
|
- 后端返回的 `msg` 字段为中文：`"操作成功"`、`"岗位名称不能重复"`
|
|
|
|
```vue
|
|
<template>
|
|
<a-button type="primary">添加岗位</a-button>
|
|
<!-- 表格列通过 columns.ts 配置 -->
|
|
</template>
|
|
```
|
|
|
|
## Ant Design Vue 中文配置
|
|
|
|
Ant Design Vue 默认支持中文，无需额外配置。如需切换语言，可通过 ConfigProvider 设置：
|
|
|
|
```vue
|
|
<template>
|
|
<a-config-provider :locale="zhCN">
|
|
<App />
|
|
</a-config-provider>
|
|
</template>
|
|
```
|
|
|
|
## 扩展方案
|
|
|
|
如需支持多语言，推荐使用 vue-i18n：
|
|
|
|
### 安装依赖
|
|
|
|
```bash
|
|
pnpm add vue-i18n
|
|
```
|
|
|
|
### 配置 i18n
|
|
|
|
```typescript
|
|
// src/i18n/index.ts
|
|
import { createI18n } from 'vue-i18n';
|
|
import zhCN from './locales/zh-CN.json';
|
|
import enUS from './locales/en-US.json';
|
|
|
|
const i18n = createI18n({
|
|
legacy: false,
|
|
locale: localStorage.getItem('lang') || 'zh-CN',
|
|
fallbackLocale: 'zh-CN',
|
|
messages: { 'zh-CN': zhCN, 'en-US': enUS },
|
|
});
|
|
|
|
export default i18n;
|
|
```
|
|
|
|
### 语言文件结构
|
|
|
|
```json
|
|
// src/i18n/locales/zh-CN.json
|
|
{
|
|
"common": {
|
|
"add": "新增",
|
|
"edit": "编辑",
|
|
"delete": "删除",
|
|
"search": "搜索",
|
|
"reset": "重置",
|
|
"confirm": "确定",
|
|
"cancel": "取消",
|
|
"success": "操作成功",
|
|
"failed": "操作失败",
|
|
"loading": "加载中..."
|
|
},
|
|
"position": {
|
|
"name": "岗位名称",
|
|
"status": "状态",
|
|
"sort": "排序",
|
|
"addTitle": "新增岗位",
|
|
"editTitle": "编辑岗位"
|
|
},
|
|
"user": {
|
|
"username": "用户名",
|
|
"realname": "真实姓名",
|
|
"email": "邮箱",
|
|
"phone": "手机号"
|
|
}
|
|
}
|
|
```
|
|
|
|
```json
|
|
// src/i18n/locales/en-US.json
|
|
{
|
|
"common": {
|
|
"add": "Add",
|
|
"edit": "Edit",
|
|
"delete": "Delete",
|
|
"search": "Search",
|
|
"reset": "Reset",
|
|
"confirm": "Confirm",
|
|
"cancel": "Cancel",
|
|
"success": "Success",
|
|
"failed": "Failed",
|
|
"loading": "Loading..."
|
|
},
|
|
"position": {
|
|
"name": "Position Name",
|
|
"status": "Status",
|
|
"sort": "Sort",
|
|
"addTitle": "Add Position",
|
|
"editTitle": "Edit Position"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 组件中使用
|
|
|
|
```vue
|
|
<template>
|
|
<a-button type="primary">{{ $t('common.add') }}</a-button>
|
|
<!-- 表格列通过 columns.ts 配置 -->
|
|
</template>
|
|
|
|
<script setup>
|
|
import { useI18n } from 'vue-i18n';
|
|
const { t } = useI18n();
|
|
</script>
|
|
```
|
|
|
|
### Ant Design Vue 国际化联动
|
|
|
|
```typescript
|
|
// 动态切换 Ant Design Vue 语言
|
|
import zhCN from 'ant-design-vue/es/locale/zh_CN';
|
|
import enUS from 'ant-design-vue/es/locale/en_US';
|
|
|
|
const locale = computed(() => {
|
|
return i18n.global.locale.value === 'zh-CN' ? zhCn : en;
|
|
});
|
|
```
|
|
|
|
```vue
|
|
<template>
|
|
<a-config-provider :locale="locale">
|
|
<App />
|
|
</a-config-provider>
|
|
</template>
|
|
```
|
|
|
|
### 语言切换
|
|
|
|
```typescript
|
|
// 切换语言
|
|
function changeLanguage(lang: string) {
|
|
i18n.global.locale.value = lang;
|
|
localStorage.setItem('lang', lang);
|
|
// 同步切换 Ant Design Vue 语言
|
|
}
|
|
```
|
|
|
|
## 后端国际化
|
|
|
|
后端返回的 `msg` 字段也需要国际化处理。有两种方案：
|
|
|
|
### 方案 1：前端映射（推荐）
|
|
|
|
前端根据错误码映射为多语言文本：
|
|
|
|
```typescript
|
|
// src/i18n/error-messages.ts
|
|
const errorMessages: Record<string, Record<string, string>> = {
|
|
'zh-CN': {
|
|
'操作成功': '操作成功',
|
|
'岗位名称不能重复': '岗位名称不能重复',
|
|
},
|
|
'en-US': {
|
|
'操作成功': 'Operation successful',
|
|
'岗位名称不能重复': 'Position name already exists',
|
|
}
|
|
};
|
|
```
|
|
|
|
### 方案 2：后端返回错误码
|
|
|
|
后端返回错误码，前端根据错误码翻译：
|
|
|
|
```python
|
|
# 后端返回错误码而非文本
|
|
R.failed(code="DUPLICATE_NAME", msg="岗位名称不能重复")
|
|
```
|
|
|
|
```typescript
|
|
// 前端根据错误码翻译
|
|
const errorMap = {
|
|
'DUPLICATE_NAME': t('position.error.duplicateName'),
|
|
};
|
|
```
|
|
|
|
:::warning 注意事项
|
|
1. Ant Design Vue 内置组件的文本（如"暂无数据"、"请选择"）通过 `locale` 属性自动切换
|
|
2. 后端返回的 `msg` 字段需要额外处理
|
|
3. 日期格式、数字格式也需要考虑国际化
|
|
:::
|
|
|
|
## 改造工作量评估
|
|
|
|
```
|
|
1. 安装 vue-i18n：✅ 简单
|
|
2. 创建语言文件：⚠️ 需要提取所有硬编码文本
|
|
3. 组件改造：⚠️ 工作量较大，每个组件都需要替换文本
|
|
4. 后端改造：❌ 需要统一错误码体系
|
|
5. 测试验证：⚠️ 每种语言都需要完整测试
|
|
```
|
|
|
|
:::tip 温馨提示
|
|
国际化改造工作量较大，建议在项目初期规划。如仅需中文，当前硬编码方式即可满足需求。改造时需要同时处理前端文本和后端返回的 `msg` 字段。
|
|
:::
|
|
|
|
## 总结
|
|
|
|
当前项目为中文单语言版本，Ant Design Vue 默认支持中文。如需扩展多语言支持，可基于 vue-i18n 实现前端国际化，配合 Ant Design Vue 内置语言包和后端消息 code 实现全链路多语言。改造需考虑前端文本、Ant Design Vue 组件、后端消息三个维度的国际化。
|