# 5、国际化
# 概述
本框架基于 vue-i18n 实现国际化（多语言），vue-i18n 是 uni-app 内置模块，无需额外 npm install。
国际化覆盖两部分：
| 部分 | 说明 | 语言包来源 |
|---|---|---|
| 开发者页面文案 | 项目中使用 $t() / this.$t() 获取的文本 | locale/lang/*.json |
| Element UI 组件文案 | Element UI 内置的分页器、日期选择器等组件文字 | element-ui/lib/locale/lang/* |
# 目录结构
├── locale/
│ ├── index.js # 语言包入口，汇总导出所有语言
│ └── lang/
│ ├── en.json # 英文翻译
│ ├── zh-Hans.json # 简体中文翻译
│ ├── zh-Hans.json # 简体中文翻译
│ └── xxx.json # 可以继续补充其它语言
1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
# main.js 配置
vk-admin 1.24.1 + 已内置，无需手动配置，低版本请更新至最新版
# 在页面中使用
# 模板中
<!-- 基本用法 -->
<el-button>{{ $t('vk.table.search') }}</el-button>
<!-- 带参数插值（参数名需与翻译文件中一致） -->
<span>{{ $t('vk.table.batchConfirmTips', { count: 5, title: '删除' }) }}</span>
1
2
3
4
5
2
3
4
5
对应的翻译文件条目：
{
"vk.table.search": "搜索",
"vk.table.batchConfirmTips": "确定对选中的 {count} 项执行【{title}】吗？"
}
1
2
3
4
2
3
4
# JS 中
// 在 methods 中使用
this.$message.success(this.$t('vk.form.success'));
// 带参数
this.$message.warning(this.$t('vk.form.fileSelect.fileSizeLimit', { name: 'test.jpg', fileSize: 10, sizeUnit: 'MB' }));
1
2
3
4
5
2
3
4
5
# data() 中
data() {
return {
// ⚠️ 只在组件创建时求值一次，切换语言后不会自动更新，需刷新页面
typeTabs: [
{ label: this.$t('vk.assetLibrary.allTypes'), value: '' },
{ label: this.$t('vk.assetLibrary.image'), value: 'image' },
],
};
},
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
# pages.json 中使用
在需要国际化的属性值中使用 %key% 占位：
{
"pages": [
{
"path": "pages/index/index",
"style": {
"navigationBarTitleText": "%index.title%"
}
}
],
"tabBar": {
"list": [
{
"pagePath": "pages/index/index",
"text": "%index.home%"
}
]
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
pages.json 支持以下属性配置国际化信息
- navigationBarTitleText
- titleNView -> titleText
- titleNView -> searchInput -> placeholder
- tabBar -> list -> text
TIP
小程序平台不支持 %key% 占位方案，需要通过 uni.setTabBarItem() 等 API 动态设置，或使用自定义 TabBar 组件替代。
# manifest.json 国际化
和 pages.json 一致，在项目根目录增加 locale/uni-app.语言地区代码.json 文件，然后在 manifest.json 中使用 %% 占位
{
"name": "%app.name%",
"appid": "",
"description": "",
"versionName": "1.0.0",
"versionCode": "100",
"locale": "zh-Hans" // 设置默认语言
}
1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
manifest.json 中支持配置应用默认语言，参见上面的示例，默认为 auto，跟随系统 OS 的语言。
# 切换语言
// 获取当前语言
let locale = uni.getLocale(); // 返回 'zh-Hans'、'en'、'zh-Hant'
// 设置语言（需刷新页面后生效）
uni.setLocale('en');
1
2
3
4
5
2
3
4
5
TIP
切换语言后必须刷新页面才能使所有文案生效，因为 data() 中通过 this.$t() 初始化的值（如 typeTabs、sortOptions）只在组件创建时求值一次。
# 新增翻译 key 的步骤
当需要在页面中新增国际化文案时，按以下步骤操作：
第 1 步：在 locale/lang/zh-Hans.json 中添加中文 key
{
"vk.myModule.title": "我的标题",
"vk.myModule.description": "这是一段描述"
}
1
2
3
4
2
3
4
第 2 步：在 locale/lang/en.json 中添加对应英文翻译
{
"vk.myModule.title": "My Title",
"vk.myModule.description": "This is a description"
}
1
2
3
4
2
3
4
第 3 步：在 locale/lang/zh-Hant.json 中添加对应繁体翻译
{
"vk.myModule.title": "我的標題",
"vk.myModule.description": "這是一段描述"
}
1
2
3
4
2
3
4
第 4 步：在页面代码中使用
<template>
<div>
<div class="title">{{ $t('vk.myModule.title') }}</div>
<div class="desc">{{ $t('vk.myModule.description') }}</div>
</div>
</template>
1
2
3
4
5
6
2
3
4
5
6