前端项目做到一半产品经理突然说“我们要支持英文版下个月还有东南亚三个语种”这种场景做过的人应该都不陌生。Vue 3 项目里做国际化绕不开 i18n 这个生态里最成熟的方案但真正上手之后你会发现装包、配 locale、写 JSON 这些只是热身真正耗时间的是切换语言时冒出来的一堆问题刷新页面语言又变回去了、某些组件里的文案死活不跟着切、日期和数字格式对不上、打包体积莫名其妙涨了一大截。这篇内容就是围绕 Vue 3 项目接入 i18n 以及语言切换过程中那些高频问题展开的从版本选型、目录组织、初始化配置到切换失效的排查链路、持久化方案、按需加载和性能取舍都会给出可以直接抄的代码和踩过坑之后的判断依据。不管你是第一次在 Vue 3 里接国际化还是已经接了但被切换问题折腾过下面这些内容应该都能对上你的场景。1. 版本选型与项目接入前的判断1.1 vue-i18n 在 Vue 3 生态里的版本分水岭很多人第一步就卡在装哪个版本上。Vue 3 必须用 vue-i18n 的 9.x 及以上版本这一点没有商量余地因为 8.x 是绑定 Vue 2 的响应式系统的装到 Vue 3 项目里要么直接报错要么在组合式 API 里拿不到响应式更新。9.x 之后官方又分了两个大方向9.x 系列保持了对旧版 API 的兼容10.x 开始则把一些历史包袱砍掉更贴近 Vue 3 的组合式写法。我的建议是新项目直接上 9.x 的较新小版本或者 10.x老项目迁移的话先看现有代码里有没有大量使用this.$t这种选项式写法如果有9.x 的兼容模式能省掉大量改造工作。这里有个容易被忽略的点legacy配置项。vue-i18n 9 默认是开启 legacy 模式的也就是同时支持选项式 API 的this.$t和组合式的useI18n。如果你确定项目是纯组合式写法可以在创建实例时把legacy: false打开这样能少加载一部分兼容代码体积会小一些。但要注意一旦关掉 legacythis.$t就彻底不能用了模板里也得改成$t的全局注入方式或者用useI18n返回的t函数。我见过有项目为了省这点体积把 legacy 关了结果某个老组件里残留的this.$t直接白屏排查了半天。import { createI18n } from vue-i18n const i18n createI18n({ legacy: false, // 纯组合式写法体积更小 locale: zh-CN, fallbackLocale: zh-CN, messages: { zh-CN: { hello: 你好 }, en-US: { hello: Hello } } })1.2 语言包的组织方式扁平还是嵌套语言包的结构直接决定了后期维护成本。扁平结构就是所有 key 平铺比如home.title、home.subtitle直接写成home.title: ...嵌套结构则是按模块分层home: { title: ..., subtitle: ... }。两种都能用但我的经验是模块数量超过十个、或者多人协作的项目一定要用嵌套结构并且按页面或功能域拆文件。扁平结构在 key 少的时候看着清爽一旦上百个 key找起来就是灾难而且很容易出现两个人起了同一个 key 名但含义不同的情况。拆文件的方式也有讲究。常见做法是src/locales/zh-CN/index.js里聚合各个模块模块文件按common.js、user.js、order.js这样分。聚合的时候用展开运算符合并注意同名模块的 key 不要冲突。另外语言包的 key 命名建议统一用英文小驼峰或者点分隔的语义化命名不要用中文拼音更不要用text1、text2这种后期根本没法维护。// src/locales/zh-CN/index.js import common from ./common import user from ./user export default { ...common, ...user }1.3 初始化配置里那几个必须想清楚的参数创建 i18n 实例时有几个参数值得单独拎出来说。locale是当前语言fallbackLocale是兜底语言这两个是基础。missingWarn和fallbackWarn建议在开发环境打开、生产环境关掉因为开发时你需要知道哪个 key 漏翻了生产环境这些警告会污染控制台还拖慢性能。silentTranslationWarn在 9.x 里已经被missingWarn取代别照着老教程配。还有一个globalInjection开启之后模板里可以直接用$t不用每个组件都useI18n。这个对迁移老项目很友好但纯组合式项目里我倾向于关掉让依赖关系更明确。另外datetimeFormats和numberFormats如果项目里涉及日期和金额展示最好在初始化时就定义好不要等到用的时候再零散配置否则格式不统一的问题会在后期集中爆发。2. 语言切换失效的排查链路2.1 切换后页面不更新先分清是响应式问题还是作用域问题语言切换最常见的现象就是点了切换按钮locale的值确实变了但页面上部分文案纹丝不动。这时候不要急着怀疑插件先做两件事。第一在控制台打印i18n.global.locale.value确认值真的变了第二看那些没更新的文案是用什么方式取的翻译。如果组件里是const { t } useI18n()然后在模板里用t(key)正常情况下是响应式的会跟着locale变。但如果有人把t(key)的结果赋给了一个普通变量或者ref的初始值那就断了响应式链路locale再变这个变量也不会重新计算。// 错误示范结果被固化切换语言不更新 const title t(home.title) // 正确示范模板里直接调用保持响应式 const { t } useI18n() // template: {{ t(home.title) }}还有一种情况是useI18n的作用域问题。在 Vue 3 里useI18n必须在setup同步执行阶段调用如果你把它放在异步回调、setTimeout或者某个条件分支里拿到的实例可能不是当前组件上下文的表现就是翻译不更新甚至报错。我遇到过一次某同学在onMounted里调useI18n开发环境没报错但切换语言就是不生效挪回setup顶层就好了。2.2 全局实例与组件实例的 locale 不同步vue-i18n 9 里有个很容易踩的坑i18n.global.locale和组件内useI18n()返回的locale在 legacy 模式下行为不一样。legacy 为 true 时i18n.global.locale是个字符串直接赋值就能切legacy 为 false 时i18n.global.locale是个 ref得用.value赋值。很多人在切换函数里写了i18n.global.locale en-US在组合式模式下这行代码不会报错但也不生效因为你在给一个 ref 对象重新赋值而不是改它的 value。// legacy: false 时的正确切换方式 import i18n from /locales function switchLang(lang) { i18n.global.locale.value lang }更稳妥的做法是封装一个统一的切换函数内部同时处理locale.value赋值、本地存储写入、以及document.documentElement.lang的更新。这样所有切换入口都走同一个函数不会出现某个按钮切了、另一个下拉框没切的情况。2.3 组件库和第三方组件的语言不跟随项目里用了组件库的话语言切换往往只切了自己写的文案组件库内置的文案分页器、日期选择器、上传组件提示等还是原来的语言。这不是 i18n 的问题而是组件库有自己的 locale 配置。以常见的组件库为例它们通常提供一个 ConfigProvider 或者类似的全局配置组件需要把当前语言对应的语言包传进去。也就是说切换语言时你要同时更新 i18n 的 locale 和组件库的 locale两套体系要联动。我的做法是在切换函数里维护一个语言映射表把 i18n 的 locale 值映射到组件库的语言包对象切换时一起更新。这样新增语言时只需要在映射表里加一行不用改切换逻辑。另外如果项目里用了日期库日期库的 locale 也要单独设置这三套i18n、组件库、日期库是独立的漏掉任何一个都会出现“半中半英”的尴尬界面。体系配置位置切换时操作vue-i18n创建实例时更新locale.value组件库ConfigProvider更新传入的 locale 对象日期库全局或局部设置调用对应的 locale 设置方法3. 刷新丢失与持久化语言状态怎么存才靠谱3.1 为什么刷新后语言会回到默认值i18n 实例的locale是内存状态页面一刷新整个 JS 环境重建locale自然回到初始化时写的默认值。这是最基础的原因但很多人第一次遇到还是会愣一下。解决办法就是把用户选择的语言持久化初始化时优先读持久化的值读不到再用浏览器语言或者默认语言兜底。持久化的位置有两个选择localStorage和cookie。纯前端项目用localStorage就够了读写简单、容量大。如果项目有服务端渲染或者需要服务端根据语言返回不同内容那就得用cookie因为服务端读不到localStorage。这里要注意localStorage存的是字符串读出来之后要校验一下是不是支持的语言别直接把一个脏值塞给locale否则会出现语言包找不到、页面全是 key 的情况。const SUPPORTED_LOCALES [zh-CN, en-US, ja-JP] function getInitialLocale() { const saved localStorage.getItem(app-locale) if (saved SUPPORTED_LOCALES.includes(saved)) { return saved } const browserLang navigator.language const matched SUPPORTED_LOCALES.find(l browserLang.startsWith(l.split(-)[0])) return matched || zh-CN }3.2 初始化时机与首屏闪烁持久化做好之后还有一个体验问题首屏渲染时如果先用了默认语言、再在onMounted里切成持久化的语言用户会看到一瞬间的文案闪烁。正确的做法是在创建 i18n 实例之前就把 locale 确定好也就是在模块加载阶段读持久化值直接作为createI18n的locale参数。这样首屏渲染出来就是正确的语言没有闪烁。如果语言包是异步加载的后面会讲那首屏闪烁的问题会更复杂因为语言包没到之前页面可能显示 key。这种情况要么在路由守卫里等语言包加载完再放行要么给一个轻量的 loading 态。我的建议是主语言包同步引入、其他语言包异步加载这样绝大多数用户首屏无闪烁只有切换语言时才走异步加载。3.3 多标签页之间的语言同步这个场景比较隐蔽用户在 A 标签页切了语言B 标签页还是旧语言两个页面同时开着就显得很割裂。localStorage的storage事件可以解决这个问题A 页写入后 B 页能监听到变化然后同步更新自己的locale。注意storage事件只在其他标签页触发当前页不会触发所以切换函数里还是要正常更新当前页。window.addEventListener(storage, (e) { if (e.key app-locale e.newValue) { i18n.global.locale.value e.newValue } })这个监听记得在应用卸载时移除虽然单页应用一般不会卸载根组件但养成习惯没坏处。另外如果项目里用了 iframe 嵌套storage事件在 iframe 和父页面之间的行为要单独验证不同浏览器的表现可能有差异。4. 异步加载与打包体积的取舍4.1 全量引入的代价语言包全量同步引入是最省事的做法但代价是打包体积。假设一个中等规模项目有 800 个翻译 key单个语言包的 JSON 大概 30 到 50KB五个语言就是 150 到 250KB这些都会进主包。对于首屏性能敏感的项目这个体积不能忽视。而且大部分用户只会用一种语言其他语言包对他们来说是纯浪费。我做过一个粗略的对比某项目全量引入四个语言包主包 gzip 后多了约 90KB改成按需加载后主包只保留当前语言其他语言在切换时动态 import主包体积回落切换语言时多一次几百毫秒的请求。这个取舍要看项目类型后台管理系统对首屏体积不敏感全量引入完全没问题面向 C 端的页面就得掂量一下。4.2 动态 import 语言包的实现方式按需加载的核心是把语言包从静态 import 改成动态 import配合setLocaleMessage把加载好的语言包注册进 i18n 实例。切换函数里先判断目标语言包是否已加载没加载就 await 动态 import加载完再切 locale。这里要注意并发问题用户快速连点切换按钮时可能有多个 import 在飞得加个加载中的状态或者用请求去重避免重复加载和状态错乱。const loadedLocales new Set([zh-CN]) async function loadLocale(lang) { if (loadedLocales.has(lang)) return const module await import(../locales/${lang}/index.js) i18n.global.setLocaleMessage(lang, module.default) loadedLocales.add(lang) } async function switchLang(lang) { await loadLocale(lang) i18n.global.locale.value lang localStorage.setItem(app-locale, lang) }动态 import 的路径不要用完全动态的变量拼接像import(../locales/${lang}.js)这种打包工具需要能静态分析出可能的模块范围否则会把整个目录都打进去或者直接失败。比较稳的写法是维护一个映射对象把语言 code 映射到具体的 import 函数这样打包工具能明确知道有哪些模块。4.3 语言包加载失败与降级异步加载就有失败的可能网络抖动、资源 404 都会导致切换卡住。这时候要有降级策略加载失败时保持当前语言不变给用户一个轻提示而不是把 locale 切过去但语言包是空的。实现上就是 try/catch 包住加载逻辑catch 里回滚状态并提示。另外fallbackLocale在这里也能兜底即使某个 key 在当前语言里缺失也会回退到兜底语言显示不至于出现空白。还有一个细节动态加载的语言包注册进 i18n 之后如果用户再次切回已加载的语言不应该重复请求。用一个 Set 或者对象记录已加载的语言切换前先查。这个记录在页面刷新后会重置但刷新后本来也只需要加载当前语言所以不影响。5. 那些不报错但很烦人的细节问题5.1 翻译 key 缺失的静默失败key 写错或者漏翻i18n 默认的行为是把 key 原样显示出来比如页面上直接出现user.profile.title。开发环境有missingWarn能提示但生产环境关掉警告后就只能靠肉眼发现。我的做法是在开发阶段加一个校验脚本扫描代码里所有t(...)的调用和语言包的 key 做比对缺的列出来。这个脚本不用很复杂正则提取加集合比对就够用能在提测前把大部分漏翻问题拦下来。另外fallbackLocale的兜底行为要理解清楚当前语言缺 key 时会用兜底语言的值但如果兜底语言也缺才会显示 key。所以兜底语言的语言包一定要保证完整通常就是开发的主语言。5.2 带参数的翻译与复数处理带变量的翻译用t(key, { name: xxx })语言包里写hello: 你好{name}。这里容易出问题的是变量名拼写语言包里的占位符和调用时传的参数名必须完全一致大小写敏感。复数处理用管道符分隔比如apple: no apples | one apple | {count} apples调用时传counti18n 会根据 count 的值选对应的分支。中文没有复数变化但英文、俄语等语言有所以语言包设计时要把复数考虑进去不要等翻译交付了才发现结构不支持。5.3 模板字符串与特殊字符的转义语言包里如果包含、|、{、}这些字符会被 i18n 当成语法符号解析导致显示异常。比如邮箱地址里的直接写会被当成 linked message 的语法。解决办法是用字面量插值把特殊字符包在{}里或者调整 message 的编译选项。这个坑在写“联系我们”这类包含邮箱的文案时特别容易踩表现就是邮箱显示不全或者报编译错误。提示语言包里出现、|、{}时优先检查是否被 i18n 的语法解析吞掉必要时用字面量插值包裹。5.4 服务端返回的文案与前端语言包的边界有些项目会把部分文案放在服务端配置里前端通过接口拿。这时候语言切换就涉及两套数据源前端语言包立即切换服务端文案要重新请求。如果处理不好会出现页面一半新语言一半旧语言。我的建议是明确边界静态 UI 文案走前端语言包动态内容比如商品描述、公告走服务端并带上语言参数切换语言时触发相关接口的重新请求。切换函数里除了更新 locale还要通知那些依赖服务端文案的模块刷新数据这个联动逻辑最好收敛到一个统一的地方不要散落在各个组件里。6. 一套可复用的切换方案落地6.1 目录结构与模块划分把前面这些点串起来一套可复用的方案大概是这样的目录结构src/locales/index.js负责创建 i18n 实例和导出切换函数src/locales/zh-CN/、src/locales/en-US/按语言分目录目录内按模块拆文件。切换函数单独放在src/locales/switch.js或者直接挂在 index 里导出内部处理 locale 更新、持久化、组件库联动、已加载语言记录这几件事。这样业务组件里只需要import { switchLang } from /locales不用关心内部细节。6.2 切换函数的完整实现与边界处理一个健壮的切换函数要处理这些边界目标语言是否支持、是否与当前语言相同、语言包是否已加载、加载失败怎么回滚、组件库 locale 怎么同步。把这些都收进函数里业务侧调用就一行。下面是一个参考实现实际项目里按需增删。import i18n from ./index import { componentLocales } from ./component-locale-map const SUPPORTED [zh-CN, en-US, ja-JP] const loaded new Set([zh-CN]) let switching false export async function switchLang(lang) { if (!SUPPORTED.includes(lang)) return false if (lang i18n.global.locale.value) return true if (switching) return false switching true try { if (!loaded.has(lang)) { const mod await import(./${lang}/index.js) i18n.global.setLocaleMessage(lang, mod.default) loaded.add(lang) } i18n.global.locale.value lang localStorage.setItem(app-locale, lang) document.documentElement.lang lang // 组件库 locale 同步具体 API 按所用组件库调整 syncComponentLocale(componentLocales[lang]) return true } catch (e) { console.error(语言切换失败, e) return false } finally { switching false } }这里的switching标志位是为了防连点避免并发加载。syncComponentLocale是个抽象具体实现取决于组件库有的用全局配置对象有的用 provide/inject按实际来。6.3 测试与回归清单国际化功能上线前建议过一遍这个清单切换语言后刷新页面语言是否保持所有页面是否有漏翻的 key用校验脚本扫组件库内置文案是否跟随日期和金额格式是否正确带参数的翻译变量是否正确替换复数语言如果支持的分支是否正确快速连点切换是否出现状态错乱弱网下切换失败是否有提示且状态可恢复。这几项过完基本能覆盖 90% 的线上问题。我在实际项目里踩得最深的一个坑是组件库 locale 没同步测试同学截图过来一半中文一半英文排查了半天才定位到是 ConfigProvider 没更新。从那以后切换函数里组件库同步这一行我都是放在最显眼的位置并且加了断言切换后校验组件库 locale 是否和 i18n 一致不一致就在控制台报警。这种防御性代码看着多余但在多人协作的项目里能省下不少沟通成本。 
长河君 · 2026/11/3 4:34:08 · 阅读 1.2k Vue 3 国际化实战：i18n 接入与语言切换高频问题全解析
前端项目做到一半产品经理突然说“我们要支持英文版下个月还有东南亚三个语种”这种场景做过的人应该都不陌生。Vue 3 项目里做国际化绕不开 i18n 这个生态里最成熟的方案但真正上手之后你会发现装包、配 locale、写 JSON 这些只是热身真正耗时间的是切换语言时冒出来的一堆问题刷新页面语言又变回去了、某些组件里的文案死活不跟着切、日期和数字格式对不上、打包体积莫名其妙涨了一大截。这篇内容就是围绕 Vue 3 项目接入 i18n 以及语言切换过程中那些高频问题展开的从版本选型、目录组织、初始化配置到切换失效的排查链路、持久化方案、按需加载和性能取舍都会给出可以直接抄的代码和踩过坑之后的判断依据。不管你是第一次在 Vue 3 里接国际化还是已经接了但被切换问题折腾过下面这些内容应该都能对上你的场景。1. 版本选型与项目接入前的判断1.1 vue-i18n 在 Vue 3 生态里的版本分水岭很多人第一步就卡在装哪个版本上。Vue 3 必须用 vue-i18n 的 9.x 及以上版本这一点没有商量余地因为 8.x 是绑定 Vue 2 的响应式系统的装到 Vue 3 项目里要么直接报错要么在组合式 API 里拿不到响应式更新。9.x 之后官方又分了两个大方向9.x 系列保持了对旧版 API 的兼容10.x 开始则把一些历史包袱砍掉更贴近 Vue 3 的组合式写法。我的建议是新项目直接上 9.x 的较新小版本或者 10.x老项目迁移的话先看现有代码里有没有大量使用this.$t这种选项式写法如果有9.x 的兼容模式能省掉大量改造工作。这里有个容易被忽略的点legacy配置项。vue-i18n 9 默认是开启 legacy 模式的也就是同时支持选项式 API 的this.$t和组合式的useI18n。如果你确定项目是纯组合式写法可以在创建实例时把legacy: false打开这样能少加载一部分兼容代码体积会小一些。但要注意一旦关掉 legacythis.$t就彻底不能用了模板里也得改成$t的全局注入方式或者用useI18n返回的t函数。我见过有项目为了省这点体积把 legacy 关了结果某个老组件里残留的this.$t直接白屏排查了半天。import { createI18n } from vue-i18n const i18n createI18n({ legacy: false, // 纯组合式写法体积更小 locale: zh-CN, fallbackLocale: zh-CN, messages: { zh-CN: { hello: 你好 }, en-US: { hello: Hello } } })1.2 语言包的组织方式扁平还是嵌套语言包的结构直接决定了后期维护成本。扁平结构就是所有 key 平铺比如home.title、home.subtitle直接写成home.title: ...嵌套结构则是按模块分层home: { title: ..., subtitle: ... }。两种都能用但我的经验是模块数量超过十个、或者多人协作的项目一定要用嵌套结构并且按页面或功能域拆文件。扁平结构在 key 少的时候看着清爽一旦上百个 key找起来就是灾难而且很容易出现两个人起了同一个 key 名但含义不同的情况。拆文件的方式也有讲究。常见做法是src/locales/zh-CN/index.js里聚合各个模块模块文件按common.js、user.js、order.js这样分。聚合的时候用展开运算符合并注意同名模块的 key 不要冲突。另外语言包的 key 命名建议统一用英文小驼峰或者点分隔的语义化命名不要用中文拼音更不要用text1、text2这种后期根本没法维护。// src/locales/zh-CN/index.js import common from ./common import user from ./user export default { ...common, ...user }1.3 初始化配置里那几个必须想清楚的参数创建 i18n 实例时有几个参数值得单独拎出来说。locale是当前语言fallbackLocale是兜底语言这两个是基础。missingWarn和fallbackWarn建议在开发环境打开、生产环境关掉因为开发时你需要知道哪个 key 漏翻了生产环境这些警告会污染控制台还拖慢性能。silentTranslationWarn在 9.x 里已经被missingWarn取代别照着老教程配。还有一个globalInjection开启之后模板里可以直接用$t不用每个组件都useI18n。这个对迁移老项目很友好但纯组合式项目里我倾向于关掉让依赖关系更明确。另外datetimeFormats和numberFormats如果项目里涉及日期和金额展示最好在初始化时就定义好不要等到用的时候再零散配置否则格式不统一的问题会在后期集中爆发。2. 语言切换失效的排查链路2.1 切换后页面不更新先分清是响应式问题还是作用域问题语言切换最常见的现象就是点了切换按钮locale的值确实变了但页面上部分文案纹丝不动。这时候不要急着怀疑插件先做两件事。第一在控制台打印i18n.global.locale.value确认值真的变了第二看那些没更新的文案是用什么方式取的翻译。如果组件里是const { t } useI18n()然后在模板里用t(key)正常情况下是响应式的会跟着locale变。但如果有人把t(key)的结果赋给了一个普通变量或者ref的初始值那就断了响应式链路locale再变这个变量也不会重新计算。// 错误示范结果被固化切换语言不更新 const title t(home.title) // 正确示范模板里直接调用保持响应式 const { t } useI18n() // template: {{ t(home.title) }}还有一种情况是useI18n的作用域问题。在 Vue 3 里useI18n必须在setup同步执行阶段调用如果你把它放在异步回调、setTimeout或者某个条件分支里拿到的实例可能不是当前组件上下文的表现就是翻译不更新甚至报错。我遇到过一次某同学在onMounted里调useI18n开发环境没报错但切换语言就是不生效挪回setup顶层就好了。2.2 全局实例与组件实例的 locale 不同步vue-i18n 9 里有个很容易踩的坑i18n.global.locale和组件内useI18n()返回的locale在 legacy 模式下行为不一样。legacy 为 true 时i18n.global.locale是个字符串直接赋值就能切legacy 为 false 时i18n.global.locale是个 ref得用.value赋值。很多人在切换函数里写了i18n.global.locale en-US在组合式模式下这行代码不会报错但也不生效因为你在给一个 ref 对象重新赋值而不是改它的 value。// legacy: false 时的正确切换方式 import i18n from /locales function switchLang(lang) { i18n.global.locale.value lang }更稳妥的做法是封装一个统一的切换函数内部同时处理locale.value赋值、本地存储写入、以及document.documentElement.lang的更新。这样所有切换入口都走同一个函数不会出现某个按钮切了、另一个下拉框没切的情况。2.3 组件库和第三方组件的语言不跟随项目里用了组件库的话语言切换往往只切了自己写的文案组件库内置的文案分页器、日期选择器、上传组件提示等还是原来的语言。这不是 i18n 的问题而是组件库有自己的 locale 配置。以常见的组件库为例它们通常提供一个 ConfigProvider 或者类似的全局配置组件需要把当前语言对应的语言包传进去。也就是说切换语言时你要同时更新 i18n 的 locale 和组件库的 locale两套体系要联动。我的做法是在切换函数里维护一个语言映射表把 i18n 的 locale 值映射到组件库的语言包对象切换时一起更新。这样新增语言时只需要在映射表里加一行不用改切换逻辑。另外如果项目里用了日期库日期库的 locale 也要单独设置这三套i18n、组件库、日期库是独立的漏掉任何一个都会出现“半中半英”的尴尬界面。体系配置位置切换时操作vue-i18n创建实例时更新locale.value组件库ConfigProvider更新传入的 locale 对象日期库全局或局部设置调用对应的 locale 设置方法3. 刷新丢失与持久化语言状态怎么存才靠谱3.1 为什么刷新后语言会回到默认值i18n 实例的locale是内存状态页面一刷新整个 JS 环境重建locale自然回到初始化时写的默认值。这是最基础的原因但很多人第一次遇到还是会愣一下。解决办法就是把用户选择的语言持久化初始化时优先读持久化的值读不到再用浏览器语言或者默认语言兜底。持久化的位置有两个选择localStorage和cookie。纯前端项目用localStorage就够了读写简单、容量大。如果项目有服务端渲染或者需要服务端根据语言返回不同内容那就得用cookie因为服务端读不到localStorage。这里要注意localStorage存的是字符串读出来之后要校验一下是不是支持的语言别直接把一个脏值塞给locale否则会出现语言包找不到、页面全是 key 的情况。const SUPPORTED_LOCALES [zh-CN, en-US, ja-JP] function getInitialLocale() { const saved localStorage.getItem(app-locale) if (saved SUPPORTED_LOCALES.includes(saved)) { return saved } const browserLang navigator.language const matched SUPPORTED_LOCALES.find(l browserLang.startsWith(l.split(-)[0])) return matched || zh-CN }3.2 初始化时机与首屏闪烁持久化做好之后还有一个体验问题首屏渲染时如果先用了默认语言、再在onMounted里切成持久化的语言用户会看到一瞬间的文案闪烁。正确的做法是在创建 i18n 实例之前就把 locale 确定好也就是在模块加载阶段读持久化值直接作为createI18n的locale参数。这样首屏渲染出来就是正确的语言没有闪烁。如果语言包是异步加载的后面会讲那首屏闪烁的问题会更复杂因为语言包没到之前页面可能显示 key。这种情况要么在路由守卫里等语言包加载完再放行要么给一个轻量的 loading 态。我的建议是主语言包同步引入、其他语言包异步加载这样绝大多数用户首屏无闪烁只有切换语言时才走异步加载。3.3 多标签页之间的语言同步这个场景比较隐蔽用户在 A 标签页切了语言B 标签页还是旧语言两个页面同时开着就显得很割裂。localStorage的storage事件可以解决这个问题A 页写入后 B 页能监听到变化然后同步更新自己的locale。注意storage事件只在其他标签页触发当前页不会触发所以切换函数里还是要正常更新当前页。window.addEventListener(storage, (e) { if (e.key app-locale e.newValue) { i18n.global.locale.value e.newValue } })这个监听记得在应用卸载时移除虽然单页应用一般不会卸载根组件但养成习惯没坏处。另外如果项目里用了 iframe 嵌套storage事件在 iframe 和父页面之间的行为要单独验证不同浏览器的表现可能有差异。4. 异步加载与打包体积的取舍4.1 全量引入的代价语言包全量同步引入是最省事的做法但代价是打包体积。假设一个中等规模项目有 800 个翻译 key单个语言包的 JSON 大概 30 到 50KB五个语言就是 150 到 250KB这些都会进主包。对于首屏性能敏感的项目这个体积不能忽视。而且大部分用户只会用一种语言其他语言包对他们来说是纯浪费。我做过一个粗略的对比某项目全量引入四个语言包主包 gzip 后多了约 90KB改成按需加载后主包只保留当前语言其他语言在切换时动态 import主包体积回落切换语言时多一次几百毫秒的请求。这个取舍要看项目类型后台管理系统对首屏体积不敏感全量引入完全没问题面向 C 端的页面就得掂量一下。4.2 动态 import 语言包的实现方式按需加载的核心是把语言包从静态 import 改成动态 import配合setLocaleMessage把加载好的语言包注册进 i18n 实例。切换函数里先判断目标语言包是否已加载没加载就 await 动态 import加载完再切 locale。这里要注意并发问题用户快速连点切换按钮时可能有多个 import 在飞得加个加载中的状态或者用请求去重避免重复加载和状态错乱。const loadedLocales new Set([zh-CN]) async function loadLocale(lang) { if (loadedLocales.has(lang)) return const module await import(../locales/${lang}/index.js) i18n.global.setLocaleMessage(lang, module.default) loadedLocales.add(lang) } async function switchLang(lang) { await loadLocale(lang) i18n.global.locale.value lang localStorage.setItem(app-locale, lang) }动态 import 的路径不要用完全动态的变量拼接像import(../locales/${lang}.js)这种打包工具需要能静态分析出可能的模块范围否则会把整个目录都打进去或者直接失败。比较稳的写法是维护一个映射对象把语言 code 映射到具体的 import 函数这样打包工具能明确知道有哪些模块。4.3 语言包加载失败与降级异步加载就有失败的可能网络抖动、资源 404 都会导致切换卡住。这时候要有降级策略加载失败时保持当前语言不变给用户一个轻提示而不是把 locale 切过去但语言包是空的。实现上就是 try/catch 包住加载逻辑catch 里回滚状态并提示。另外fallbackLocale在这里也能兜底即使某个 key 在当前语言里缺失也会回退到兜底语言显示不至于出现空白。还有一个细节动态加载的语言包注册进 i18n 之后如果用户再次切回已加载的语言不应该重复请求。用一个 Set 或者对象记录已加载的语言切换前先查。这个记录在页面刷新后会重置但刷新后本来也只需要加载当前语言所以不影响。5. 那些不报错但很烦人的细节问题5.1 翻译 key 缺失的静默失败key 写错或者漏翻i18n 默认的行为是把 key 原样显示出来比如页面上直接出现user.profile.title。开发环境有missingWarn能提示但生产环境关掉警告后就只能靠肉眼发现。我的做法是在开发阶段加一个校验脚本扫描代码里所有t(...)的调用和语言包的 key 做比对缺的列出来。这个脚本不用很复杂正则提取加集合比对就够用能在提测前把大部分漏翻问题拦下来。另外fallbackLocale的兜底行为要理解清楚当前语言缺 key 时会用兜底语言的值但如果兜底语言也缺才会显示 key。所以兜底语言的语言包一定要保证完整通常就是开发的主语言。5.2 带参数的翻译与复数处理带变量的翻译用t(key, { name: xxx })语言包里写hello: 你好{name}。这里容易出问题的是变量名拼写语言包里的占位符和调用时传的参数名必须完全一致大小写敏感。复数处理用管道符分隔比如apple: no apples | one apple | {count} apples调用时传counti18n 会根据 count 的值选对应的分支。中文没有复数变化但英文、俄语等语言有所以语言包设计时要把复数考虑进去不要等翻译交付了才发现结构不支持。5.3 模板字符串与特殊字符的转义语言包里如果包含、|、{、}这些字符会被 i18n 当成语法符号解析导致显示异常。比如邮箱地址里的直接写会被当成 linked message 的语法。解决办法是用字面量插值把特殊字符包在{}里或者调整 message 的编译选项。这个坑在写“联系我们”这类包含邮箱的文案时特别容易踩表现就是邮箱显示不全或者报编译错误。提示语言包里出现、|、{}时优先检查是否被 i18n 的语法解析吞掉必要时用字面量插值包裹。5.4 服务端返回的文案与前端语言包的边界有些项目会把部分文案放在服务端配置里前端通过接口拿。这时候语言切换就涉及两套数据源前端语言包立即切换服务端文案要重新请求。如果处理不好会出现页面一半新语言一半旧语言。我的建议是明确边界静态 UI 文案走前端语言包动态内容比如商品描述、公告走服务端并带上语言参数切换语言时触发相关接口的重新请求。切换函数里除了更新 locale还要通知那些依赖服务端文案的模块刷新数据这个联动逻辑最好收敛到一个统一的地方不要散落在各个组件里。6. 一套可复用的切换方案落地6.1 目录结构与模块划分把前面这些点串起来一套可复用的方案大概是这样的目录结构src/locales/index.js负责创建 i18n 实例和导出切换函数src/locales/zh-CN/、src/locales/en-US/按语言分目录目录内按模块拆文件。切换函数单独放在src/locales/switch.js或者直接挂在 index 里导出内部处理 locale 更新、持久化、组件库联动、已加载语言记录这几件事。这样业务组件里只需要import { switchLang } from /locales不用关心内部细节。6.2 切换函数的完整实现与边界处理一个健壮的切换函数要处理这些边界目标语言是否支持、是否与当前语言相同、语言包是否已加载、加载失败怎么回滚、组件库 locale 怎么同步。把这些都收进函数里业务侧调用就一行。下面是一个参考实现实际项目里按需增删。import i18n from ./index import { componentLocales } from ./component-locale-map const SUPPORTED [zh-CN, en-US, ja-JP] const loaded new Set([zh-CN]) let switching false export async function switchLang(lang) { if (!SUPPORTED.includes(lang)) return false if (lang i18n.global.locale.value) return true if (switching) return false switching true try { if (!loaded.has(lang)) { const mod await import(./${lang}/index.js) i18n.global.setLocaleMessage(lang, mod.default) loaded.add(lang) } i18n.global.locale.value lang localStorage.setItem(app-locale, lang) document.documentElement.lang lang // 组件库 locale 同步具体 API 按所用组件库调整 syncComponentLocale(componentLocales[lang]) return true } catch (e) { console.error(语言切换失败, e) return false } finally { switching false } }这里的switching标志位是为了防连点避免并发加载。syncComponentLocale是个抽象具体实现取决于组件库有的用全局配置对象有的用 provide/inject按实际来。6.3 测试与回归清单国际化功能上线前建议过一遍这个清单切换语言后刷新页面语言是否保持所有页面是否有漏翻的 key用校验脚本扫组件库内置文案是否跟随日期和金额格式是否正确带参数的翻译变量是否正确替换复数语言如果支持的分支是否正确快速连点切换是否出现状态错乱弱网下切换失败是否有提示且状态可恢复。这几项过完基本能覆盖 90% 的线上问题。我在实际项目里踩得最深的一个坑是组件库 locale 没同步测试同学截图过来一半中文一半英文排查了半天才定位到是 ConfigProvider 没更新。从那以后切换函数里组件库同步这一行我都是放在最显眼的位置并且加了断言切换后校验组件库 locale 是否和 i18n 一致不一致就在控制台报警。这种防御性代码看着多余但在多人协作的项目里能省下不少沟通成本。