150 lines
2.9 KiB
Markdown
150 lines
2.9 KiB
Markdown
# 国际化
|
||
|
||
项目使用 [Vue i18n](https://kazupon.github.io/vue-i18n/) 进行国际化处理。
|
||
|
||
## 基础用法
|
||
|
||
```ts
|
||
// 路由配置中使用
|
||
import { $t } from '#/locales';
|
||
|
||
const routes = [
|
||
{
|
||
meta: {
|
||
title: $t('page.home.title'),
|
||
},
|
||
name: 'Home',
|
||
path: '/home',
|
||
component: () => import('#/views/home/index.vue'),
|
||
},
|
||
];
|
||
```
|
||
|
||
```vue
|
||
<!-- 组件中使用 -->
|
||
<script setup lang="ts">
|
||
import { $t } from '#/locales';
|
||
</script>
|
||
|
||
<template>
|
||
<div>{{ $t('common.confirm') }}</div>
|
||
</template>
|
||
```
|
||
|
||
## 语言配置
|
||
|
||
在 `preferences.ts` 中设置默认语言：
|
||
|
||
```ts
|
||
import { defineOverridesPreferences } from '@vben/preferences';
|
||
|
||
export const overridesPreferences = defineOverridesPreferences({
|
||
app: {
|
||
locale: 'zh-CN', // 'en-US' | 'zh-CN' | ...
|
||
},
|
||
});
|
||
```
|
||
|
||
## 支持的语言
|
||
|
||
```ts
|
||
type SupportedLanguagesType =
|
||
| 'en-US'
|
||
| 'zh-CN'
|
||
| 'zh-TW'
|
||
| 'ko-KR'
|
||
| 'ru-RU'
|
||
| 'ja-JP';
|
||
```
|
||
|
||
## 语言包位置
|
||
|
||
```
|
||
packages/locales/
|
||
├── langs/ # 语言包文件
|
||
│ ├── en-US.json
|
||
│ ├── zh-CN.json
|
||
│ └── ...
|
||
└── src/ # 国际化相关代码
|
||
```
|
||
|
||
## 新增语言包
|
||
|
||
1. 在 `packages/locales/langs/` 目录下新建语言文件，如 `ja-JP.json`
|
||
2. 在 `packages/types/src.ts` 中添加类型定义
|
||
3. 在 `preferences.ts` 中配置 `locale: 'ja-JP'`
|
||
|
||
## 语言包结构示例
|
||
|
||
```json
|
||
{
|
||
"common": {
|
||
"confirm": "确认",
|
||
"cancel": "取消",
|
||
"save": "保存",
|
||
"delete": "删除",
|
||
"search": "搜索",
|
||
"reset": "重置"
|
||
},
|
||
"page": {
|
||
"home": {
|
||
"title": "首页",
|
||
"welcome": "欢迎"
|
||
}
|
||
},
|
||
"ui": {
|
||
"formRules": {
|
||
"required": "请输入{0}",
|
||
"selectRequired": "请选择{0}"
|
||
},
|
||
"placeholder": {
|
||
"input": "请输入",
|
||
"select": "请选择"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 消息语法边界
|
||
|
||
Vue i18n 会把 `@` 解析为 linked message 起始符。文案需要显示普通 `@` 时必须使用字面量插值 `{'@'}`，不能直接写裸 `@`，否则生产消息编译器可能抛出 `SyntaxError: 14`。
|
||
|
||
新增或修改业务语言包后，应通过实际 i18n runtime 逐条调用对应 namespace，并断言没有 message compilation error。网络管理的回归入口为 `test/views/system/network/network-locale.spec.ts`。
|
||
|
||
## 远程加载语言包
|
||
|
||
```ts
|
||
// 支持从远程服务器加载语言包
|
||
import { setI18nLanguage } from '@vben/locales';
|
||
|
||
async function loadLocaleMessages(locale: string) {
|
||
const messages = await fetch(`/locales/${locale}.json`).then((res) =>
|
||
res.json(),
|
||
);
|
||
setI18nLanguage(locale, messages);
|
||
}
|
||
```
|
||
|
||
## 切换语言
|
||
|
||
框架内置了语言切换组件，可通过偏好设置开启：
|
||
|
||
```ts
|
||
export const overridesPreferences = defineOverridesPreferences({
|
||
widget: {
|
||
languageToggle: true, // 显示语言切换按钮
|
||
},
|
||
});
|
||
```
|
||
|
||
## 在代码中切换
|
||
|
||
```ts
|
||
import { useLocale } from '@vben/locales';
|
||
|
||
const { changeLocale } = useLocale();
|
||
|
||
// 切换到英文
|
||
changeLocale('en-US');
|
||
```
|