Vue+i18n
1. 基本概念
Vue I18n是一个基于Vue.js的国际化插件,它允许开发者在Vue应用中轻松实现多语言支持。通过Vue I18n,开发者可以将应用中的文本内容抽象为语言包,然后根据用户的语言偏好动态加载相应的语言包。这样,应用就可以根据不同的语言环境显示不同的文本内容。Vue 官方推荐使用 vue-i18n 插件进行国际化实现。本篇文档总结 Vue + vue-i18n 在 H5 多语言方案中的功能和应用。
2. 工作原理
Vue I18n的工作原理主要基于Vue的响应式系统和插件机制。它首先会扫描Vue组件中的文本内容,并将其标记为可翻译的文本。然后,Vue I18n会根据当前的语言环境,从相应的语言包中查找对应的翻译文本,并将其替换到组件中。由于Vue的响应式系统,当语言环境发生变化时,Vue I18n会自动更新组件中的文本内容,保持与语言环境的同步。
3. vue-i18n 基本功能
3.1. 多语言配置
- 定义语言包:通过 messages 对象定义不同语言的文本。
- 默认语言:可以设置默认显示的语言。
- 备用语言:当当前语言中未找到某个翻译时,可以回退到备用语言。
示例代码:
const i18n = new VueI18n({
locale: 'en', // 默认语言
fallbackLocale: 'en', // 备用语言
messages: {
en: { hello: 'Hello' },
zh: { hello: '你好' },
},
});
3.2. 文本渲染
vue-i18n 提供了 $t 方法来获取对应语言的翻译文本。
<template>
<div>{{ $t('hello') }}</div>
</template>
// en: Hello / zh: 你好
3.3. 动态切换语言
可以通过修改 this.$i18n.locale 来动态切换语言。
<template>
<div>
<p>{{ $t('hello') }}</p>
<button @click="changeLang('en')">English</button>
<button @click="changeLang('zh')">中文</button>
</div>
</template>
<script>
export default {
methods: {
changeLang(lang) {
this.$i18n.locale = lang; // 切换语言
},
},
};
</script>
3.4. 参数占位与动态文本
vue-i18n 支持带参数的占位符,实现动态文本替换。
const messages = {
en: { greeting: 'Hello, {name}!' },
zh: { greeting: '你好,{name}!' },
};
<p>{{ $t('greeting', { name: 'Tom' }) }}</p>
// en:Hello, Tom! / zh:你好,Tom!
3.5. 复数处理
支持复数规则,根据数量动态显示不同的文本。
const messages = {
en: {
apple: 'No apples | One apple | {count} apples',
},
zh: {
apple: '没有苹果 | 一个苹果 | {count} 个苹果',
},
};
<p>{{ $tc('apple', 0) }}</p> <!-- No apples -->
<p>{{ $tc('apple', 1) }}</p> <!-- One apple -->
<p>{{ $tc('apple', 5, { count: 5 }) }}</p> <!-- 5 apples -->
3.6. 格式化日期和数字
const messages = {
en: { date: 'Current date: {date}' },
zh: { date: '当前日期:{date}' },
};
<template>
<div>
<p>{{ $t('date', { date: new Date().toLocaleDateString() }) }}</p>
<p>{{ $n(123456.789, 'currency') }}</p>
</div>
</template>
<script>
export default {
methods: {
// 使用 $n 方法对数字进行本地化
$n(value, type) {
return new Intl.NumberFormat(this.$i18n.locale, { style: type, currency: 'USD' }).format(value);
},
},
};
</script>
// 英文:Current date: 12/31/2024
// 中文:当前日期:2024/12/31
// 数字:123,456.79(按货币格式化)
3.7. 语言文件拆分与异步加载
const i18n = new VueI18n({
locale: 'en',
fallbackLocale: 'en',
messages: {}, // 初始为空
});
// 动态加载语言包
async function loadLanguageAsync(lang) {
if (!i18n.getLocaleMessage(lang)) {
const messages = await import(`@/locales/${lang}.json`);
i18n.setLocaleMessage(lang, messages.default);
}
i18n.locale = lang;
}
4. 优势
简单易用:提供 i18n.locale 等 API,方便文本渲染与语言切换。
多语言配置灵活:可扩展多语言包,通过 JSON 或对象统一管理文本。
动态替换参数:支持占位符,实现动态插值。
性能优化:仅加载当前语言包,适合大型项目使用。
支持回退语言:当前语言缺少文本时自动回退备用语言,提升健壮性。
5. 缺点
包体积较大: vue-i18n 的功能比较多,因此引入后会增加项目的包体积。
配置复杂度: 管理多语言包的配置较为繁琐,语言包拆分和维护需要额外投入精力。
首屏性能影响: 当语言包较大时,加载语言资源可能会增加首屏时间。
6. 使用:
6.1. 安装:vue2 安装版本需要 <= 8
npm install vue-i18n@8 --save
6.2. 创建配置文件
在 src 目录下创建 i18n/index.ts,用于初始化:
// src/i18n/index.ts
import Vue from 'vue';
import VueI18n from 'vue-i18n';
Vue.use(VueI18n);
const messages = {
en: {
hello: 'Hello',
welcome: 'Welcome to our App',
},
zh: {
hello: '你好',
welcome: '欢迎使用我们的应用',
},
};
const i18n = new VueI18n({
locale: 'en', // 设置默认语言
fallbackLocale: 'en', // 备用语言
messages,
});
export default i18n;
6.3. 挂载
在 main.js 中引入 i18n 并挂载到 Vue 实例中:
// src/main.ts
import Vue from 'vue';
import App from './App.vue';
import i18n from './i18n'; // 引入 i18n
Vue.config.productionTip = false;
new Vue({
i18n, // 挂载 i18n 实例
render: h => h(App),
}).$mount('#app');
6.4. 在组件中使用
<template>
<div>
<!-- 使用 $t 方法来翻译文本 -->
<p>{{ $t('hello') }}</p>
<p>{{ $t('welcome') }}</p>
<!-- 切换语言按钮 -->
<button @click="changeLanguage('en')">English</button>
<button @click="changeLanguage('zh')">中文</button>
</div>
</template>
<script>
export default {
methods: {
changeLanguage(lang) {
this.$i18n.locale = lang; // 动态切换语言
},
},
};
</script>
7. 开发插件 - i18n Ally
VSCode 的 i18n Ally 插件
7.1. 功能:
- 自动识别语言文件:
-
- 支持识别常见国际化工具的语言文件,如 vue-i18n 的 JSON 格式文件。
- 自动扫描项目中的 src/locales 或指定路径的语言文件。
- 语言文件预览与编辑:
-
- 在代码中 快速预览 国际化文本内容,无需切换文件。
- 支持 直接编辑 语言文件,修改时自动更新。
- 快捷键快速跳转与定位:
-
- 通过 快捷键 快速定位到对应的语言文件,提升开发效率。
- 支持从代码中直接跳转到语言键所在的 JSON 文件。
- 语言键自动补全:
-
- 在代码中输入 $t('') 时,插件会自动提示可用的语言键,减少拼写错误和重复操作。
- 通过补全功能,可以快速找到已经定义的国际化文本。
- 语言缺失检查:
-
- 自动检测各语言文件中是否缺失翻译内容。
- 直观显示未翻译的键,确保各个语言的完整性。
- 多语言预览:
-
- 在编辑页面时,支持实时预览不同语言的翻译效果。
- 开发者可以在编辑器中切换语言,检查多语言界面内容。
7.2. 安装与配置
在 VSCode 扩展市场搜索 i18n Ally 并安装。
在 settings.json 中进行基础配置:
{
"i18n-ally.localesPaths": ["src/i18n"], // 指定语言文件路径
"i18n-ally.keystyle": "nested", // 设置语言文件的格式,如嵌套格式
"i18n-ally.sourceLanguage": "en", // 设置默认语言
"i18n-ally.displayLanguage": "zh" // 编辑器中显示的预览语言
}