详解 vue-i18n：让你的 Vue 项目支持多语言

随着全球化趋势的深入，越来越多的应用程序需要面向不同语言和文化背景的用户。一个支持多语言的应用程序不仅能够扩大用户群体，提升用户体验，更是现代软件开发不可或缺的一部分。在 Vue.js 生态系统中，vue-i18n 是实现国际化（Internationalization，简称 i18n）和本地化（Localization，简称 l10n）事实上的标准库。

本文将深入探讨 vue-i18n 的各个方面，从基础安装配置到高级功能，再到实际应用中的最佳实践，帮助你轻松地为你的 Vue 项目添加多语言支持。

1. 什么是国际化（i18n）和本地化（l10n）？

在开始学习 vue-i18n 之前，我们先来明确两个核心概念：

国际化 (Internationalization, i18n)：这个词的英文有18个字母介于 ‘i’ 和 ‘n’ 之间，因此简称 i18n。它是一个设计和开发过程，旨在使产品易于适应不同的语言和区域设置，而无需对核心代码进行工程更改。i18n 的目标是使应用程序具备多语言和多区域适应的能力。它通常包括将所有面向用户的文本、日期、时间、货币等从代码中抽象出来，放入外部资源文件中。
本地化 (Localization, l10n)：这个词的英文有10个字母介于 ‘l’ 和 ‘n’ 之间，因此简称 l10n。它是一个具体实施过程，是将已经国际化过的产品根据特定目标语言和区域设置进行调整，使其符合当地的语言习惯、文化背景、技术标准等。l10n 包括翻译文本、调整日期/时间/数字/货币格式、处理单位、考虑文化习俗等。

简单来说，i18n 是让你的应用“准备好”支持多种语言，而 l10n 则是实际为它“配备”特定的语言和地区内容。vue-i18n 就是帮助我们在 Vue 项目中完成 i18n 和 l10n 的有力工具。

2. 为什么选择 vue-i18n？

Vue.js 生态集成：作为官方推荐的国际化库，vue-i18n 与 Vue.js 的核心特性（如响应式系统、组件化）深度集成，使用起来非常顺畅。
简单易用：提供了简洁的 API，无论是新手还是有经验的开发者都能快速上手。
功能丰富：支持文本翻译、插值、复数形式、日期时间格式化、数字格式化等多种功能。
高性能：经过优化，对应用性能影响较小。
社区活跃：拥有广泛的用户群体和活跃的社区支持，遇到问题容易找到解决方案。

3. 安装和基本配置

开始使用 vue-i18n 非常简单，首先通过 npm 或 yarn 进行安装。请注意，vue-i18n 有两个主要版本分支，分别对应 Vue 2 和 Vue 3。

对于 Vue 3 项目:

“`bash
npm install vue-i18n@next

或

yarn add vue-i18n@next
`` 这里的@next指的是vue-i18n` v9.x 或更高版本，专门为 Vue 3 设计。
对于 Vue 2 项目:

“`bash
npm install vue-i18n@8

或

yarn add vue-i18n@8
`` 这里的@8指的是vue-i18n` v8.x 版本，适用于 Vue 2。

安装完成后，我们需要在应用入口文件（通常是 main.js 或 main.ts）中进行配置。

3.1 Vue 3 配置示例

“`javascript
// main.js
import { createApp } from ‘vue’
import { createI18n } from ‘vue-i18n’
import App from ‘./App.vue’

// 1. 定义语言包
const messages = {
en: {
message: {
hello: ‘Hello world’,
welcome: ‘Welcome, {name}!’,
pluralExample: ‘You have {count} apple | You have {count} apples’,
formattedDate: ‘The date is: {date}’,
formattedNumber: ‘The price is: {price}’
},
validation: {
required: ‘This field is required.’
}
},
zh: {
message: {
hello: ‘你好世界’,
welcome: ‘欢迎您，{name}！’,
pluralExample: ‘您有 {count} 个苹果’, // 中文的复数形式通常不区分
formattedDate: ‘日期是：{date}’,
formattedNumber: ‘价格是：{price}’
},
validation: {
required: ‘这是必填项。’
}
}
}

// 2. 创建 i18n 实例
const i18n = createI18n({
// 选项 API 模式，需要显式指定 legacy: false 才能使用 Composition API
// 如果你主要使用 Options API，可以不设置或设置为 true
legacy: false,
// 默认语言
locale: ‘en’,
// 回退语言，当当前语言找不到对应翻译时，会尝试使用回退语言
fallbackLocale: ‘en’,
// 语言包
messages,
// 如果你使用 Composition API，需要将 globalInjection 设置为 true
// 这样在 Options API 中也能通过 this.$t 访问
globalInjection: true,
});

// 3. 将 i18n 实例挂载到 Vue 应用上
const app = createApp(App)
app.use(i18n)
app.mount(‘#app’)
“`

3.2 Vue 2 配置示例

“`javascript
// main.js
import Vue from ‘vue’
import VueI18n from ‘vue-i18n’
import App from ‘./App.vue’

Vue.use(VueI18n)

// 1. 定义语言包
const messages = {
en: {
message: {
hello: ‘Hello world’,
welcome: ‘Welcome, {name}!’,
pluralExample: ‘You have {count} apple | You have {count} apples’,
formattedDate: ‘The date is: {date}’,
formattedNumber: ‘The price is: {price}’
},
validation: {
required: ‘This field is required.’
}
},
zh: {
message: {
hello: ‘你好世界’,
welcome: ‘欢迎您，{name}！’,
pluralExample: ‘您有 {count} 个苹果’,
formattedDate: ‘日期是：{date}’,
formattedNumber: ‘价格是：{price}’
},
validation: {
required: ‘这是必填项。’
}
}
}

// 2. 创建 i18n 实例
const i18n = new VueI18n({
// 默认语言
locale: ‘en’,
// 回退语言
fallbackLocale: ‘en’,
// 语言包
messages,
});

// 3. 将 i18n 实例挂载到 Vue 根实例上
new Vue({
i18n, // 添加 i18n 配置
render: h => h(App),
}).$mount(‘#app’)
“`

在上述配置中：
* 我们创建了一个 messages 对象，它包含了不同语言（en, zh）对应的翻译文本。这些文本通常组织成嵌套的对象结构，以便更好地管理。
* 我们使用 createI18n (Vue 3) 或 new VueI18n (Vue 2) 创建了一个 i18n 实例。
* locale 选项设置了应用的当前语言环境，默认为 ‘en’。
* fallbackLocale 设置了回退语言。当当前语言环境中找不到某个翻译键时，vue-i18n 会尝试在回退语言中寻找，这有助于提高应用的健壮性。
* messages 选项传入了我们定义的语言包。
* 最后，将 i18n 实例通过 app.use(i18n) (Vue 3) 或添加到 Vue 根实例的选项中 (Vue 2) 挂载到 Vue 应用中。

4. 在组件中使用翻译文本

配置完成后，vue-i18n 会将 $t、$d、$n 等全局辅助函数注入到 Vue 实例和组件实例中，方便我们在模板和脚本中使用。

4.1 在模板中使用 `$t`

在 Vue 模板中，你可以使用 $t 辅助函数来显示翻译文本。

“`vue

“`

这里，$t('message.hello') 会根据当前语言环境查找 messages 对象中 message.hello 对应的值并显示。

$t 函数的第一个参数是消息的 key。第二个参数（可选）是一个对象，用于消息中的插值。

4.2 在脚本中使用 `$t`

你也可以在组件的 <script> 部分使用 $t，例如在计算属性、方法或生命周期钩子中。

Vue 2 (Options API):

javascript export default { name: 'MyComponent', computed: { greetingMessage() { return this.$t('message.welcome', { name: 'Guest' }); } }, methods: { showAlert() { alert(this.$t('validation.required')); } } }
在 Vue 2 的 Options API 中，$t 直接通过 this 访问。
Vue 3 (Options API):

javascript export default { name: 'MyComponent', computed: { greetingMessage() { // Vue 3 Options API 可以直接通过 this.$t 访问， // 前提是你在 createI18n 时设置了 globalInjection: true return this.$t('message.welcome', { name: 'Guest' }); } }, methods: { showAlert() { alert(this.$t('validation.required')); } } }
在 Vue 3 的 Options API 中，如果 globalInjection: true，使用方式与 Vue 2 相同。
Vue 3 (Composition API):

“`javascript
import { useI18n } from ‘vue-i18n’;
import { computed } from ‘vue’;

export default {
name: ‘MyComponent’,
setup() {
const { t } = useI18n(); // 使用 useI18n 钩子获取翻译函数
```
const greetingMessage = computed(() => {
  return t('message.welcome', { name: 'Guest' });
});

const showAlert = () => {
  alert(t('validation.required'));
};

return {
  greetingMessage,
  showAlert
};
```
}
}
`` 在 Vue 3 的 Composition API 中，推荐使用useI18n钩子来获取翻译函数t`。这是更符合 Composition API 习惯的方式。

5. 核心功能详解

5.1 消息定义与结构

如前所述，消息（翻译文本）通常存储在 JSON 或 JavaScript 对象中。一个良好的结构能够帮助你更好地组织和管理翻译内容。常见的组织方式有两种：

按语言文件组织: 每个语言一个文件，内部按模块或功能划分。
- locales/en.json
- locales/zh.json
- locales/fr.json
json // locales/en.json { "header": { "title": "My App", "greeting": "Hello, {name}" }, "footer": { "copyright": "© 2023 Company" }, "buttons": { "save": "Save", "cancel": "Cancel" } }
按模块文件组织: 每个模块一个文件，内部包含所有语言的翻译。这种方式更常见于大型应用，特别是结合代码分割时。
- components/Header/locales.js
- views/Dashboard/locales.js
javascript // components/Header/locales.js export default { en: { title: 'My App', greeting: 'Hello, {name}' }, zh: { title: '我的应用', greeting: '你好，{name}' } }

无论哪种方式，关键是使用清晰、有意义的 key。避免使用像 text1, labelA 这样的 key，而是使用描述性强的 key，例如 message.welcome, button.save, validation.required。

5.2 插值 (Interpolation)

插值允许你在翻译文本中包含动态内容。使用 {placeholder} 语法定义占位符，然后将包含占位符值的对象作为 $t 函数的第二个参数传入。

“`vue

“`

链接消息 (Linked messages):
你可以将一个消息的 key 链接到另一个消息。使用 @: 语法。

json { "greeting": "Hello", "farewell": "Goodbye", "welcome_message": "{greeting}, {name}!", "goodbye_message": "{farewell}, {name}!" }

“`vue

“`

链接消息非常有用，可以避免重复翻译相同的短语。

5.3 复数形式 (Pluralization)

不同的语言对于复数形式有不同的规则。vue-i18n 支持通过管道符 | 来定义不同数量对应的文本。

json { "en": { "car": "no cars | one car | {count} cars", "apple": "You have {count} apple | You have {count} apples" }, "fr": { "car": "aucune voiture | une voiture | {count} voitures" }, "zh": { "car": "您有 {count} 辆车", "apple": "您有 {count} 个苹果" } }

使用时，将数量作为 $t 函数的第三个参数传入。

“`vue

“`

vue-i18n 内部使用 Intl.PluralRules API（如果浏览器支持）或自己的规则来判断给定数量对应哪个复数形式。对于中文等语言，复数形式通常不随数量变化，只需要提供一个形式即可。

5.4 日期时间本地化 (Datetime Localization)

vue-i18n 提供了 $d 辅助函数来格式化日期时间。你需要提前定义好日期时间格式。

首先，在创建 i18n 实例时添加 datetimeFormats 选项：

javascript const i18n = createI18n({ // 或 new VueI18n for Vue 2 // ...其他选项 datetimeFormats: { en: { short: { year: 'numeric', month: 'short', day: 'numeric' }, long: { year: 'numeric', month: 'long', day: 'numeric', weekday: 'long', hour: 'numeric', minute: 'numeric' } }, zh: { short: { year: 'numeric', month: 'short', day: 'numeric' }, long: { year: 'numeric', month: 'long', day: 'numeric', weekday: 'long', hour: 'numeric', minute: 'numeric', hour12: false // 中文习惯使用24小时制 } } } });

然后在模板或脚本中使用 $d：

“`vue

“`

$d 函数接收三个参数：要格式化的日期对象、定义的格式名称、可选的语言环境（默认为当前语言环境）。datetimeFormats 的定义遵循 Intl.DateTimeFormat 的选项格式。

5.5 数字本地化 (Number Localization)

类似地，vue-i18n 提供了 $n 辅助函数来格式化数字（如货币、百分比）。你需要定义数字格式。

在创建 i18n 实例时添加 numberFormats 选项：

javascript const i18n = createI18n({ // 或 new VueI18n for Vue 2 // ...其他选项 numberFormats: { en: { currency: { style: 'currency', currency: 'USD', minimumFractionDigits: 2 }, percent: { style: 'percent', minimumFractionDigits: 0, maximumFractionDigits: 2 } }, zh: { currency: { style: 'currency', currency: 'CNY', minimumFractionDigits: 2 }, percent: { style: 'percent', minimumFractionDigits: 0, maximumFractionDigits: 2 } } } });

然后在模板或脚本中使用 $n：

“`vue

“`

$n 函数接收三个参数：要格式化的数字、定义的格式名称、可选的语言环境。numberFormats 的定义遵循 Intl.NumberFormat 的选项格式。

6. 动态切换语言

vue-i18n 使得动态切换应用语言变得非常容易。你只需要修改 i18n 实例的 locale 属性即可。

Vue 3:

“`javascript
// 在 setup 函数中
import { useI18n } from ‘vue-i18n’;

export default {
setup() {
const { locale } = useI18n();
```
const switchLanguage = (lang) => {
  locale.value = lang; // 使用 .value 来修改 ref
};

return {
  switchLanguage
};
```
}
}

// 或者在 Options API 中 (如果 globalInjection: true)
export default {
methods: {
switchLanguage(lang) {
this.$i18n.locale = lang;
}
}
}

// 或者直接访问 i18n 实例 (在 setup 外)
import { i18n } from ‘./main.js’; // 假设你导出了 i18n 实例
i18n.global.locale.value = ‘new-locale’;
“`
Vue 2:

javascript export default { methods: { switchLanguage(lang) { this.$i18n.locale = lang; } } }

当 locale 属性改变时，所有使用 $t、$d、$n 的地方都会响应式地更新显示对应的语言内容。这通常通过一个语言切换器组件来实现。

“`vue

“`

7. 高级用法

7.1 组件内本地化 (Component-level Localization)

除了全局语言包，你还可以在单个组件内部定义自己的翻译文本。这些文本会与全局语言包合并，组件内部使用的 $t 会优先查找组件内的文本。

“`vue

“`

这种方式适用于那些文本仅在特定组件中使用的场景，有助于提高组件的内聚性和可重用性。但是，如果同一个文本被多个组件使用，最好还是将其放在全局语言包中。

7.2 异步加载语言包 (Lazy Loading Locales)

随着项目变大，语言包文件可能会变得非常庞大，一次性加载所有语言包会影响应用启动性能。vue-i18n 支持异步加载语言包，通常结合 Webpack 或 Vite 的动态 import() 实现。

“`javascript
// locales.js – 一个负责加载语言包的辅助文件
import { nextTick } from ‘vue’; // 或 nextTick for Vue 2

// 假设 i18n 实例已经被导出
import { i18n } from ‘./main’;

const loadedLanguages = [‘en’]; // 已加载的语言列表

export async function loadLanguageAsync(lang) {
// 如果语言已经加载且不是当前语言，则直接切换
if (loadedLanguages.includes(lang)) {
if (i18n.global.locale.value !== lang) {
i18n.global.locale.value = lang; // Vue 3
// i18n.locale = lang; // Vue 2
}
return nextTick();
}

try {
// 动态导入语言包
const messages = await import(./locales/${lang}.json);
// 设置语言包并切换语言
i18n.global.setLocaleMessage(lang, messages.default); // Vue 3
// i18n.setLocaleMessage(lang, messages); // Vue 2
loadedLanguages.push(lang);
i18n.global.locale.value = lang; // Vue 3
// i18n.locale = lang; // Vue 2
return nextTick();
} catch (e) {
console.error(Error loading language ${lang}, e);
// 可以选择加载回退语言或显示错误信息
return Promise.reject(e);
}
}

// 在需要切换语言的地方调用 loadLanguageAsync
// 例如：
// loadLanguageAsync(‘zh’);
“`

在上面的例子中，loadLanguageAsync 函数首先检查语言是否已经加载，如果是，则直接切换；否则，通过 import() 动态加载对应的 JSON 文件，然后使用 setLocaleMessage 方法将加载的语言包添加到 i18n 实例中，最后切换语言。

这种方式可以显著减少初始加载时间，特别是在你的应用支持很多种语言时。

7.3 处理缺失消息 (Missing Message Handler)

如果你的代码使用了某个 key，但在当前语言或回退语言中都找不到对应的翻译，vue-i18n 默认会直接显示那个 key。你可以通过配置 missingHandler 来改变这种行为。

javascript const i18n = createI18n({ // 或 new VueI18n for Vue 2 // ...其他选项 missingHandler: (locale, key, vm, values) => { // 在这里处理缺失的 key // 例如：记录警告，或者返回一个特定的字符串 console.warn(`Missing translation for key: ${key} in locale: ${locale}`); return `[MISSING] ${key}`; // 显示一个提示性的字符串 }, });

missingHandler 函数接收四个参数：
* locale: 当前语言环境
* key: 缺失的 key
* vm: Vue 实例 (Vue 2) 或组件实例 (Vue 3)
* values: 传入的插值对象

通过定义 missingHandler，你可以在开发过程中更容易发现未翻译的文本，并在生产环境中提供更友好的用户体验，而不是直接显示丑陋的 key。

7.4 与路由集成 (Integrating with Vue Router)

常见的国际化网站会将语言环境信息放在 URL 中，例如 /en/about, /zh/about。你可以将 vue-i18n 与 Vue Router 集成来实现这一功能。

基本思路是：
1. 在路由配置中包含语言参数，例如 /langs/:locale/:pathMatch(.*)*。
2. 在路由守卫 (beforeEach) 中读取 URL 中的 locale 参数。
3. 调用 loadLanguageAsync 函数（上面定义的异步加载函数）来加载并切换语言。
4. 如果没有 locale 参数，可以尝试根据浏览器语言或用户设置来确定默认语言。

“`javascript
// router/index.js
import { createRouter, createWebHistory } from ‘vue-router’;
// import { createRouter, createWebHistory } from ‘vue-router/auto’ // for Vue 3 with vite-plugin-vue-router

import HomeView from ‘../views/HomeView.vue’;
import AboutView from ‘../views/AboutView.vue’;
import { loadLanguageAsync } from ‘../locales/locales.js’; // 导入异步加载函数

const router = createRouter({
history: createWebHistory(import.meta.env.BASE_URL),
routes,
});

export default router;
“`

在这个例子中，所有实际页面都作为带 :locale 参数的根路径的子路由。beforeEnter 守卫会确保语言被正确加载和切换。

7.5 测试国际化

测试国际化相关的代码可能有点棘手。你可以：
1. 模拟 $t, $d, $n 函数: 在单元测试中，你可以 mock vue-i18n 的全局或组件内的辅助函数，让它们返回预期的字符串，而不是实际进行翻译查找。
2. 使用测试工具加载 i18n: 使用 @vue/test-utils 等工具挂载组件时，可以传入一个配置好的 i18n 实例，然后在测试中检查渲染出的文本是否正确。

“`javascript
// Example using @vue/test-utils and vue-i18n in Vue 3
import { mount } from ‘@vue/test-utils’;
import { createI18n } from ‘vue-i18n’;
import MyComponent from ‘./MyComponent.vue’;

const messages = {
en: {
message: {
hello: ‘Hello test!’
}
},
zh: {
message: {
hello: ‘你好测试！’
}
}
};

const i18n = createI18n({
legacy: false,
locale: ‘en’,
messages,
});

describe(‘MyComponent’, () => {
it(‘renders correctly with English’, () => {
const wrapper = mount(MyComponent, {
global: {
plugins: [i18n] // 将 i18n 插件添加到全局配置
}
});
// Assumes MyComponent uses $t(‘message.hello’)
expect(wrapper.text()).toContain(‘Hello test!’);
});

it(‘renders correctly with Chinese after changing locale’, async () => {
// 创建一个独立的 i18n 实例用于这个测试
const zhI18n = createI18n({
legacy: false,
locale: ‘en’, // 初始是英文
messages,
});

const wrapper = mount(MyComponent, {
  global: {
    plugins: [zhI18n]
  }
});

// 切换语言环境
zhI18n.global.locale.value = 'zh';

// 等待 Vue 更新 DOM
await wrapper.vm.$nextTick();

// 检查是否渲染了中文
expect(wrapper.text()).toContain('你好测试！');

});
});
“`

8. 最佳实践

集中管理消息: 将所有翻译文本保存在专门的文件或目录中，而不是分散在各个组件的代码里（组件内本地化用于非常特定的场景）。
使用有意义的 Key: Key 应该清晰地描述其对应的文本内容或用途，有助于开发者理解和维护。
避免字符串拼接: 不要写 this.$t('prefix') + variable + this.$t('suffix') 这样的代码。完整的句子应该作为一个整体进行翻译，使用插值来处理动态部分，例如 this.$t('welcome_message', { name: variable })。这对于翻译者来说更容易理解和翻译，也能处理不同语言的语序差异。
提供回退语言: 确保 fallbackLocale 配置正确，当找不到翻译时，用户不会看到缺失的 key。
使用翻译管理平台: 对于大型项目，手动管理和翻译大量的 JSON 文件会变得非常困难。考虑使用专业的翻译管理平台（如 Phrase, Lokalise, Transifex 等）来协作翻译、导入导出、进行质量控制。这些平台通常支持 vue-i18n 的文件格式。
考虑语言环境和地区: 有时候，仅有语言是不够的，你可能还需要考虑地区（如 en-US vs en-GB）。vue-i18n 完全支持这种格式的 locale。
与设计师/文案人员协作: 翻译不仅仅是简单的词语替换，还需要考虑用户界面布局和文化适应性。与相关人员紧密协作，确保翻译在UI中显示良好，并且符合目标用户的习惯。
性能优化: 对于大型应用，考虑异步加载语言包以减少初始加载时间。

9. 总结

vue-i18n 是一个强大且灵活的 Vue.js 国际化库。通过本文的详细介绍，你应该已经掌握了从基础配置、在组件中使用翻译，到处理插值、复数、日期、数字格式化，再到动态切换语言、异步加载和与路由集成等高级用法。

实现多语言支持是提升应用用户体验和市场竞争力的重要一步。投入时间和精力进行良好的国际化和本地化，将为你的应用带来更广阔的未来。现在，就开始在你的 Vue 项目中实践 vue-i18n 吧！

详解 vue-i18n：让你的 Vue 项目支持多语言 – wiki基地