vue-i18n 快速上手：从零开始为 Vue 2 应用接入国际化（Getting Started 完整指南）-平芜编程栈

前端
国际化

【免费下载链接】vue-i18n

:globe_with_meridians: Internationalization plugin for Vue.js

项目地址：https://gitcode.com/gh_mirrors/vu/vue-i18n

导读

本文是 vue-i18n 官方《开始使用》（Getting Started / Iniciando）指南的完整中文讲解，面向第一次接触 vue-i18n 的开发者：只需一个 HTML 文件或一个vue-i18n的 NPM 包，就能在几分钟内为 Vue 2 应用引入多语言翻译能力。读完本文，你将掌握 vue-i18n 的完整初始化流程（消息字典定义 →VueI18n实例创建 →Vue实例挂载）、模板中$t的用法，以及这套流程在仓库源码层面的底层实现原理，可以直接照着动手跑通第一个多语言应用。

准备工作：先安装 vue-i18n

vue-i18n 是 Vue.js 的官方国际化插件，要求 Vue 2.0.0 及以上版本（兼容性说明见安装文档）。安装方式有三种，任选其一：

方式一：CDN 直接引入（最简单，适合快速体验）

在 HTML 中先引入 Vue，再引入 vue-i18n 的 UMD 构建（vue-i18n.js）。由于 vue-i18n 支持自动安装，引入后无需手动调用Vue.use()：

<script src="https://unpkg.com/vue/dist/vue.js"></script> <script src="https://unpkg.com/vue-i18n@8"></script>

https://unpkg.com/vue-i18n@8会始终指向 NPM 上的最新 v8 版本；如需固定版本，可以写成https://unpkg.com/vue-i18n@8.17.5/dist/vue-i18n.js这样的 URL。

方式二：NPM 安装

npm install vue-i18n@8

方式三：Yarn 安装

yarn add vue-i18n@8

使用模块系统（例如通过 vue-cli 构建的项目）时，必须在入口文件中显式注册插件：

import Vue from 'vue' import VueI18n from 'vue-i18n' Vue.use(VueI18n)

注意：只有使用全局<script>标签引入时才不需要手动Vue.use()；使用模块系统则必须显式调用，否则插件不会生效。使用 Vue CLI 3.x 的项目还可以通过vue add i18n一条命令完成插件脚手架安装。

第一步：编写 HTML 模板

在页面中放置一个挂载点#app，在模板里用$t("message.hello")输出翻译后的文案。$t是 vue-i18n 注入到 Vue 实例上的翻译方法，"message.hello"是消息字典中的键路径（keypath）：

<div id="app"> <p>{{ $t("message.hello") }}</p> </div>

这里message.hello是一个点分路径，它对应消息字典中message对象下的hello属性。vue-i18n 内部正是通过路径解析器（src/path.js）按点号逐级查找的。

第二步：定义本地化消息字典

接下来准备一份包含多个语言的消息字典（locale messages）。字典是一个以语言代码为键的嵌套对象，语言代码下再按业务结构组织翻译文本。官方示例同时提供了英语（en）和葡萄牙语（pt）两份翻译：

// Mensagens traduzidas de suas localidades const messages = { en: { message: { hello: 'Hello World' } }, pt: { message: { hello: 'Olá Mundo' } } }

消息字典的结构非常自由：既可以是这样简单的两级嵌套，也可以按业务模块组织成多级对象，甚至可以用数组配合$tc实现复数翻译。在 test/unit/basic.test.js 中可以看到，i18n.t('message.hello')的返回结果与messages.en.message.hello严格相等，验证了这套路径查找逻辑的正确性。

第三步：创建 VueI18n 实例

用刚才的字典创建国际化实例，并通过locale选项指定当前语言：

// Crie uma instância do VueI18n com opções const i18n = new VueI18n({ locale: 'pt', // Defina uma localidade messages, // Defina as mensagens })

这里locale: 'pt'表示应用当前使用葡萄牙语。从 src/index.js 的构造函数实现可以看到，locale的默认值是'en-US'，messages的默认值是空对象{}，而fallbackLocale（回退语言）的默认值同样是'en-US'——也就是说即使你不显式配置，插件也会自动为你准备一套语言与回退机制。

构造函数中的关键初始化逻辑

深入看源码会发现，VueI18n实例内部通过_initVM()（src/index.js）创建了一个隐藏的内部 Vue 实例来承载locale、fallbackLocale、messages、dateTimeFormats、numberFormats这几份响应式数据。这意味着：

语言切换是响应式的：locale数据变化会驱动所有订阅了翻译的组件重新渲染；
消息字典可以动态更新：messages也是响应式数据，运行期可以通过setLocaleMessage/mergeLocaleMessage等方法增改翻译。

这是 vue-i18n 能在运行时实时切换语言的根基，也是"热更新"（hot reload）类功能得以实现的前提。

第四步：挂载到 Vue 应用

把i18n实例通过i18n选项传入根 Vue 实例，然后挂载到#app：

// Crie uma instância Vue com a opção `i18n` new Vue({ i18n }).$mount('#app') // Pronto agora o aplicativo foi iniciado!

至此应用已经成功启动，页面渲染结果如下：

<div id="app"> <p>Olá Mundo</p> </div>

因为locale被设置为'pt'，所以$t("message.hello")取到的是葡萄牙语翻译Olá Mundo。

小提示：官方示例输出中写的是<div id="#app">，这是文档里的笔误；实际挂载点就是<div id="app">，上述渲染结果已按正确写法给出。

底层原理：Vue.use(VueI18n) 到底做了什么？

上面几步看似简单，背后是install插件机制在起作用。阅读 src/install.js 可以看到，Vue.use(VueI18n)触发install后主要完成了四件事：

版本校验：检查 Vue 主版本号，低于 2 时输出警告vue-i18n need to use Vue 2.0 or later；
原型注入（src/extend.js）：在Vue.prototype上定义$i18n属性，并注入$t、$tc、$te、$d、$n等全局方法，其中$t的签名是(key, ...values)，最终调用内部_t(key, locale, messages, vm, ...values)完成翻译；
全局混入（src/mixin.js）：通过Vue.mixin注入beforeCreate/beforeMount/beforeDestroy钩子。beforeCreate中会读取组件选项里的i18n：如果传入的是VueI18n实例则直接使用；如果是普通配置对象则为该组件新建一个VueI18n实例；如果组件自身没有配置，则向上继承根实例的$i18n——这就是所有子组件无需手动传参即可直接使用$t的原因；
注册指令与组件：注册v-t指令以及<i18n>插值组件、数字/日期格式化组件，让国际化能力覆盖模板指令和组件化场景。

从 src/index.js 还能看到一个贴心的设计：在浏览器环境中，如果window.Vue已存在但插件尚未手动安装，VueI18n构造函数会自动调用install(window.Vue)完成安装——这正是 CDN 方式"引入即用、无需Vue.use()"的原因。

在真实项目里跑通这个示例

仓库中已经提供了一个完整可运行的最小示例 examples/started/index.html，它的结构与官方文档完全一致：

<script src="../../node_modules/vue/dist/vue.min.js"></script> <script src="../../dist/vue-i18n.min.js"></script> ... <script> var messages = { en: { message: { hello: 'hello world' } }, ja: { message: { hello: 'こんにちは、世界' } } } Vue.use(VueI18n) var i18n = new VueI18n({ locale: 'ja', messages: messages }) new Vue({ i18n: i18n }).$mount('#app') </script>

该示例使用的是仓库本地构建产物（node_modules/vue与dist/vue-i18n.min.js），并显式调用了Vue.use(VueI18n)。在项目根目录执行npm install与npm run build生成dist产物后，直接用浏览器打开这个 HTML 即可看到日文翻译こんにちは、世界渲染在页面上。注意：示例中同时展示了显式Vue.use()的写法，这在浏览器全局脚本场景下是安全的（重复安装会被install.installed标记拦截，见 src/install.js）。

试试切换语言

掌握了基本流程后，最自然的下一步就是动态切换语言。由于locale是响应式数据，直接赋值即可触发全应用重新翻译：

// 切换到英语 i18n.locale = 'en' // 或通过组件实例访问 this.$i18n.locale = 'en'

切换后，模板中的$t("message.hello")会自动渲染为Hello World。这也是 vue-i18n 的核心体验：业务代码只写键路径，语言切换完全与视图解耦。更进阶的能力（复数$tc、日期$d、数字$n、回退语言fallbackLocale、消息合并等）都建立在本文这套初始化流程之上，可继续参考 vuepress 指南目录下的对应章节深入学习。

小结

本文带你走完了 vue-i18n 从安装到渲染出多语言页面的完整流程：引入插件 → 定义 messages 字典 →new VueI18n({ locale, messages })→new Vue({ i18n })挂载。同时结合仓库源码解释了Vue.use的安装机制、$t的原型注入、mixin 的实例共享逻辑以及内部响应式数据模型。现在你已经可以动手为下一个 Vue 2 项目接入国际化，并把语言切换做成真实可用的功能了。