Vue3+Vue-I18n+TypeScript下动态设置i18n语言的正确方式

问题原因 #

在Vue I18n v11.x版本中，尽管开启了legacy: false的组合式API模式，i18n.global.locale运行时实际是Ref<string>对象，但TypeScript的类型推导错误地将其识别为string类型，导致编译时出现Property 'value' does not exist on type 'string'的报错。

解决方案 #

方案1：类型断言快速修复

直接在赋值时将locale断言为Ref<string>，绕过类型检查：

const setLanguage = (language: string) => {
  (i18n.global.locale as Ref<string>).value = language
  localStorage.setItem('language', language)
}

方案2：使用useI18n钩子（推荐）

如果是在组件内实现语言切换，更符合组合式API规范的做法是使用useI18n钩子获取正确类型的locale：

// 组件内部代码
import { useI18n } from 'vue-i18n'

const { locale } = useI18n()
const setLanguage = (language: string) => {
  locale.value = language
  localStorage.setItem('language', language)
}

方案3：扩展I18n实例类型（非组件环境适用）

如果需要在非组件文件（如工具类、全局配置）中使用，可以手动扩展I18n实例的类型，让TypeScript正确识别locale的Ref类型：

import type { Ref } from 'vue'
import { createI18n } from 'vue-i18n'

// 自定义I18n实例类型
interface CustomI18nInstance extends ReturnType<typeof createI18n<[MessageSchema], string>> {
  global: {
    locale: Ref<string>
  }
}

const i18n = createI18n<[MessageSchema], string>({
  legacy: false,
  locale: localStorage.getItem('language') || 'en',
  fallbackLocale: 'en',
  messages: await loadMessages()
}) as CustomI18nInstance

const setLanguage = (language: string) => {
  i18n.global.locale.value = language
  localStorage.setItem('language', language)
}

export { i18n, setLanguage }

补充说明 #

调试模式下代码能正常运行，是因为运行时i18n.global.locale确实是带有value属性的Ref对象，只是TypeScript的类型定义未正确匹配运行时实际值，导致编译阶段报错。

内容的提问来源于stack exchange，提问作者daisy