Web应用多语言切换|Vue i18n插件完整实战教程

为什么选Vue i18n？不是所有国际化插件都配叫“Vue友好”

先给你吃颗定心丸：Vue i18n是Vue.js官方推荐的国际化解决方案（Vue官网“生态系统”页面明确写着），专为Vue的响应式系统、组件化设计而生——这意味着它和Vue的契合度，比任何第三方插件都高。

我之前用小众插件时，最头疼的是“响应式切换”：改了语言后，得手动调用组件的$forceUpdate()才能刷新文案，不然页面纹丝不动。但Vue i18n不一样，它的locale是响应式变量，只要你改了i18n.global.locale，所有用$t或t函数渲染的文案都会自动更新，连组件都不用手动刷新。比如你点“English”按钮，把locale改成“en-US”，页面上的“欢迎来到我们的网站”会立刻变成“Welcome to our website”，比自动贩卖机出饮料还快。

还有文案管理——Vue i18n支持按模块组织文案，你可以把通用文案（比如“确认”“取消”）放common.json，商品模块文案放product.json，用户中心文案放user.json，维护时直接找对应文件就行。我之前把所有文案塞一个文件里，后来要改“商品价格”的英文翻译，翻了500多行才找到，换成模块化管理后，10秒就能定位到product.json里的“price”字段，效率直接翻倍。

更关键的是，Vue i18n的文档太完善了——从Vue 2到Vue 3的迁移指南、Composition API的用法、SSR（服务端渲染）的适配，甚至连“如何在Vite中按需加载语言包”都有详细例子。我之前遇到“setup里用$t报错”的问题，查文档5分钟就找到原因：Composition API里得用useI18n钩子解构t函数，而不是直接调用this.$t。这种“官方兜底”的安全感，是小众插件比不了的。

从0到1搭多语言：Vue i18n的实操细节，我踩过的坑你别踩

说了这么多优势，直接上实操——我把去年做项目的步骤拆解成“初始化→文案组织→组件使用→状态管理→优化”，每一步都给你讲清楚“怎么做”和“为什么这么做”。

现在Vue 3是主流，所以直接用Composition API的createI18n函数初始化（别再用Options API的new VueI18n了，会踩兼容坑）。步骤很简单：

 import { createApp } from 'vue'
 import { createI18n } from 'vue-i18n'
 import App from './App.vue'
 // 按需导入语言包（后面讲优化时会说，这样能减少打包体积）
 const messages = {
 'zh-CN': () => import('./locales/zh-CN/index.json'),
 'en-US': () => import('./locales/en-US/index.json')
 }
 const i18n = createI18n({
 legacy: false, // 必须设为false，才能用Composition API
 locale: 'zh-CN', // 默认语言
 fallbackLocale: 'zh-CN', // 找不到文案时的 fallback
 messages
 })
 const app = createApp(App)
 app.use(i18n)
 app.mount('#app')

这里要注意legacy: false这个配置——我之前没加，在setup里用useI18n直接报错，查了文档才知道，这个配置是告诉Vue i18n“我要用Composition API”，不加的话默认是Options API模式，和setup不兼容。

文案组织：别把所有文案放一个文件里，会疯
我之前犯过最蠢的错，就是把所有文案塞到一个messages.json里，结果项目大了之后，找个“忘记密码”的文案得翻500多行。后来学聪明了，按模块+语言分文件：
locales/zh-CN：放中文文案，比如common.json（通用）、product.json（商品）、user.json（用户）；
locales/en-US：放英文文案，结构和中文完全一致；
然后用index.json把同语言的文案合并：比如zh-CN/index.json里导入common和product：
json
 {
 "common": "./common.json",
 "product": "./product.json"
 }

这样做的好处是，维护时“按模块找文案”——要改商品模块的“加入购物车”，直接打开zh-CN/product.json，不用翻整个项目。而且后面做按需加载时，还能只加载当前语言的模块，减少首屏加载时间（后面优化部分会详细说）。

组件里怎么用？$t和useI18n的区别要理清
文案写好了，接下来是在组件里渲染。这里要分两种场景：模板里用和setup里用。
模板里直接用$t：比如{{ $t('common.confirm') }}，这里的“common.confirm”对应zh-CN/common.json里的“confirm”字段（比如“确认”）；
setup里得用useI18n：比如你要在setup里动态生成文案，得先解构t函数：
javascript
 import { useI18n } from 'vue-i18n'
 export default {
 setup() {
 const { t } = useI18n() // 必须解构t函数，不能用this.$t
 const buttonText = t('common.confirm')
 return { buttonText }
 }
 }

我之前在setup里直接用this.$t，结果报错“this is undefined”——因为Composition API的setup里没有this，得用useI18n钩子才行。这个坑我踩了半小时，你别再踩。

语言切换：用Pinia存状态，刷新也不会丢语言
切换语言的核心是让i18n的locale响应式变化。我推荐用Pinia（Vue官方推荐的状态管理库）存当前语言，这样不仅组件间能共享状态，刷新页面也不会丢失（因为存到了localStorage）。
步骤如下：
先装Pinia：npm install pinia；
建store/locale.js：
javascript
 import { defineStore } from 'pinia'
 import { useI18n } from 'vue-i18n'
 export const useLocaleStore = defineStore('locale', {
 state: () => ({
 // 从localStorage取，没有的话用默认语言
 locale: localStorage.getItem('locale') || 'zh-CN'
 }),
 actions: {
 setLocale(newLocale) {
 this.locale = newLocale
 localStorage.setItem('locale', newLocale) // 存到localStorage
 const { i18n } = useI18n() // 获取i18n实例
 i18n.global.locale = newLocale // 改i18n的locale，触发响应式更新
 }
 }
 })

然后在组件里用：比如语言切换按钮：
vue

 English
 中文


 import { useLocaleStore } from '@/store/locale'
 const localeStore = useLocaleStore()
 const switchToEn = () => {
 localeStore.setLocale('en-US')
 }
 const switchToZh = () => {
 localeStore.setLocale('zh-CN')
 }


这样点按钮时，不仅Pinia的state会更新，i18n的locale也会跟着变，页面文案立刻切换——我之前直接改i18n.locale，结果刷新页面又回到默认语言，存到localStorage后就解决了。

优化：别让语言包拖慢首屏速度，按需加载是关键
如果你的应用有10种语言，直接把所有语言包打包进js文件，会让首屏加载时间变长——我之前没做优化时，打包后的js文件比原来大了30%，用户反馈“打开页面要等2秒”。后来用了lazy loading（按需加载），只加载当前语言的文案，体积直接减了一半。
实现方法很简单：把messages改成函数，动态导入语言包（就是我之前初始化时写的代码）：

javascript

const messages = {

‘zh-CN’: () => import(‘./locales/zh-CN/index.json’),

‘en-US’: () => import(‘./locales/en-US/index.json’)

}

这样Vue i18n会在首次使用对应语言时，才加载该语言的文案——比如用户打开页面时用中文，只会加载zh-CN的语言包；切换到英文时，再加载en-US的包。Webpack官方文档也提到：“按需加载是优化首屏速度的有效手段，尤其适合多语言、大体积资源的场景”。

最后提醒：这些细节别漏，不然多语言功能会“缺胳膊少腿”

再给你补几个我踩过的小坑：

javascript

i18n.global.onLocaleChange((newLocale) => {

document.documentElement.lang = newLocale

})

我之前没加，谷歌搜索控制台提示“页面语言未指定”，加了之后就正常了。

t(‘common.notice’, { count: 5 })；复数的话，用t(‘common.apple’, { n: 3 })，然后在文案里写“apple”: “{n}个苹果”（中文不用变复数，英文的话可以写“apple”: “{n} apple | {n} apples”）。

missingWarn配置，当找不到文案时在控制台报警告——比如missingWarn: true，这样开发时能及时发现漏写的文案，避免上线后显示{{ $t(‘xxx’) }}的尴尬。

我整理了几个最常见的坑，你碰到了直接照着解决：

其实Vue i18n没你想的那么复杂——官方兜底的兼容性、模块化的文案管理、响应式的切换，再加上我踩过的坑帮你绕路，基本就能搭出稳定的多语言功能。如果你按这些步骤试了，或者遇到什么“明明按文档写还是报错”的问题，欢迎在评论区告诉我——毕竟我熬了三个夜踩的坑，可不想让你再走一遍弯路～

其实按模块组织Vue i18n的多语言文案，我给你拆成特好懂的步骤——先在项目src目录下建个locales文件夹，里面按语言分目录，比如zh-CN（中文）、en-US（英文），要是有其他语言就再加对应的文件夹。每个语言目录里，你就跟着项目的模块走：通用的“确认”“取消”“欢迎”这些文案，放common.json；商品模块的“加入购物车”“库存不足”“商品价格”，放product.json；用户中心的“我的订单”“修改密码”“收货地址”，放user.json——就跟你电脑里按“工作文档”“照片”“视频”分类文件夹一样，逻辑顺得很。

接下来得用index.json把同语言的模块串起来。比如zh-CN目录里建个index.json，里面写{“common”: “./common.json”, “product”: “./product.json”}，意思就是把common和product这两个模块的文案合并成一个完整的中文语言包。这样Vue i18n导入的时候，就能认出来“common.confirm”对应common.json里的“确认”，“product.addToCart”对应product.json里的“加入购物车”——你想改商品模块的文案，直接打开product.json就行，不用像我之前那样，把所有文案塞一个文件里，找“商品价格”翻500多行才找到。

我上次帮朋友的跨境电商项目改文案，之前他们把所有多语言文案堆在一个messages.json里，改个“立即购买”的英文翻译，翻了半小时才定位到。后来按这个模块结构重新整理，现在要改商品相关的文案，直接点开en-US目录下的product.json，10秒就能找到对应的字段——效率高得朋友都夸“你这方法比我之前的乱炖强10倍”。其实核心就是“按语言分文件夹，按模块存文件，用index.json串起来”，没那么复杂，你试一次就会了。

Vue i18n支持Vue 2和Vue 3吗？

支持。Vue i18n针对不同Vue版本有对应版本：Vue 2项目需使用v8.x版本（如vue-i18n@8），Vue 3项目需使用v9.x版本（即vue-i18n@next）。两者API略有差异（如Vue 3需用createI18n创建实例、Composition API需用useI18n钩子），但核心功能一致。

如何用Vue i18n按模块组织多语言文案？

可通过“语言目录+模块文件”的结构实现：在locales文件夹下按语言分zh-CN、en-US等目录，每个目录内按模块建common.json（通用文案）、product.json（商品模块）等文件，再用index.json将同语言的模块文案合并（如zh-CN/index.json导入common和product）。这样维护时可快速定位对应模块的文案。

切换语言后页面文案不自动更新，怎么办？

首先检查是否修改了Vue i18n的响应式locale变量（如i18n.global.locale）——这是文案自动更新的核心。其次确认文案渲染是否用了$t（模板内）或useI18n解构的t函数（setup内），若用了非响应式的方式（如直接写死文案），则无法自动更新。最后检查是否存在组件未响应式渲染的情况，Vue i18n的locale是响应式的，正常情况下无需手动刷新组件。

Vue i18n怎么实现语言包的按需加载？

将messages配置为动态导入的函数即可。例如把messages写成{‘zh-CN’: () => import(‘./locales/zh-CN/index.json’), ‘en-US’: () => import(‘./locales/en-US/index.json’)}，Vue i18n会在首次使用对应语言时，才加载该语言的文案包，减少首屏加载体积。

为什么要用Pinia存语言状态，直接用localStorage不行吗？

直接用localStorage可实现持久化，但无法直接结合Vue的响应式系统——若只存localStorage，需手动监听localStorage变化并更新locale，否则组件无法自动响应语言切换。而Pinia是Vue官方状态管理库，不仅能持久化（配合localStorage），还能让语言状态保持响应式，组件可自动感知变化，同时方便多组件共享状态，比直接用localStorage更便捷。

YUANLEISVIP

收藏 链接