Vue I12 中的重大变更

移除传统 API 模式

原因: 传统 API 模式已在 v11 中被废弃，正如 v11 重大变更 中宣布的那样。它是与 Vue I18n v8 兼容的 API 模式，用于平滑地从 v8 迁移到 v9。

在 v12 中，传统 API 模式已被完全移除。createI18n 中的 legacy 选项不再可用，所有应用程序必须使用组合 API 模式。

被移除的内容

• createI18n 中的 legacy: true 选项
• VueI18n 实例（传统接口）
• VueI18nOptions 类型
• allowComposition 选项（因为组合 API 是唯一模式，不再需要）
• 依赖于 VueI18n 实例的传统特定注入 API

以前（v11）

import { createI18n } from 'vue-i18n'

// 传统 API 模式
const i18n = createI18n({
  legacy: true, // 早期版本中这是默认值
  locale: 'en',
  messages: {
    en: { hello: 'Hello!' },
    ja: { hello: 'こんにちは！' }
  }
})

// 通过 VueI18n 实例访问
i18n.global.locale = 'ja'

<!-- 在选项 API 组件中 -->
<template>
  <p>{{ $t('hello') }}</p>
</template>

<script>
export default {
  mounted() {
    // 通过 this.$i18n 访问（VueI18n 实例）
    console.log(this.$i18n.locale)
    this.$i18n.locale = 'ja'
  }
}
</script>

现在（v12）

import { createI18n } from 'vue-i18n'

// 组合 API 模式（唯一可用的模式）
const i18n = createI18n({
  locale: 'en',
  messages: {
    en: { hello: 'Hello!' },
    ja: { hello: 'こんにちは！' }
  }
})

// 通过 Composer 实例访问
i18n.global.locale.value = 'ja'

<!-- 使用组合 API -->
<template>
  <p>{{ t('hello') }}</p>
</template>

<script setup>
import { useI18n } from 'vue-i18n'

const { t, locale } = useI18n()

// 更改语言环境
locale.value = 'ja'
</script>

<!-- 使用组合 API 的选项 API -->
<template>
  <p>{{ t('hello') }}</p>
</template>

<script>
import { useI18n } from 'vue-i18n'

export default {
  setup() {
    const { t, locale } = useI18n()
    return { t, locale }
  }
}
</script>

迁移

1. 从 createI18n 中移除 legacy: true 选项
2. 将语言环境访问从 i18n.global.locale 更改为 i18n.global.locale.value
3. 将 this.$i18n 用法替换为 setup 函数中的 useI18n()
4. 将 this.$t() 替换为 useI18n() 中的 t()

有关详细迁移指南，请参见：

• 从传统 API 模式迁移到组合 API 模式
• 组合 API 使用

移除自定义指令 v-t

原因: 此自定义指令已在 v12 中警告即将被移除。文档说明，https://vue-i18n.intlify.dev/guide/migration/breaking11.html#deprecate-custom-directive-v-t

更改 MissingHandler 签名

原因: Vue 3.6+ 废弃了 getCurrentInstance() API。MissingHandler 类型以前接收 ComponentInternalInstance 作为第三个参数，但现在不再可用。

以前（v11）

type MissingHandler = (
  locale: Locale,
  key: Path,
  instance?: ComponentInternalInstance,
  type?: string
) => string | void

const i18n = createI18n({
  missing: (locale, key, instance, type) => {
    // instance 是 ComponentInternalInstance
    console.warn(`Missing: ${key}`, instance?.uid)
  }
})

现在（v12）

type MissingHandler = (
  locale: Locale,
  key: Path,
  uid?: number,
  type?: string
) => string | void

const i18n = createI18n({
  missing: (locale, key, uid, type) => {
    // 现在直接传入 uid 作为数字
    console.warn(`Missing: ${key}`, uid)
  }
})

迁移

将 instance 参数替换为 uid：

  const i18n = createI18n({
-  missing: (locale, key, instance, type) => {
-    console.warn(`Missing key "${key}" in ${locale}`, instance?.uid)
+  missing: (locale, key, uid, type) => {
+    console.warn(`Missing key "${key}" in ${locale}`, uid)
    }
  })