迁移指南

按照本指南从 v9.x 升级到 v10.x

升级到 Vue I18n v11

我们已将 Vue I18n 从 v10 升级到 v11，此主要版本更新已弃用 Legacy API 模式和自定义的 v-t 指令，并且从 Legacy API 模式中移除了 tc() 和 $tc()。

请查看关于破坏性变更的详细文档这里。

配置选项

以下配置选项已被更改、弃用或移除。

状态	选项	说明
promoted	`experimental.hmr`	默认启用，并更名为 `hmr`
promoted	`experimental.switchLocalePathLinkSSR`	默认启用，且不再提供禁用此功能的选项。
promoted	`experimental.autoImportTranslationFunctions`	默认启用，并更名为 `autoDeclare`
changed	`restructureDir`	该选项不能再被禁用。建议保持未设置状态以使用默认值 `'i18n'`。
deprecated	`types`	v11 只支持 `'composition'` 类型，与 Vue I18n v12 保持一致。
deprecated	`baseUrl`	v11 仅允许字符串值，不再支持函数配置。复杂场景请使用运行时配置或依赖多域名本地化设置基地址。
deprecated	`routesNameSeparator`	文档中标记为内部使用，终端用户的使用场景不明确。
deprecated	`defaultLocaleRouteNameSuffix`	文档中标记为内部使用，终端用户的使用场景不明确。
removed	`lazy`	现在所有的语言包文件均启用懒加载。
removed	`bundle.optimizeTranslationDirective`	该功能已被禁用并彻底移除，详细上下文见此议题讨论。
removed	`experimental.generatedLocaleFilePathFormat`	本模块对文件路径（例如语言包文件、vue-i18n 配置）相关配置已完全移除，使此选项过时。

行为变化

浏览器语言检测

语言检测和重定向的改进遵循了文档中严格的行为。在 v9 中，某些 strategy 和 redirectOn 选项的组合表现出意外的行为，这在 v10 中已得到修正。

关键变化：当使用 strategy: 'prefix' 和 redirectOn: 'root' 时，非根路径（例如 '/search'）将不再自动重定向到其本地化版本（例如 '/zh/search'）。

迁移：如果您需要对所有路径使用前缀策略进行重定向，请更新您的配置：

export default defineNuxtConfig({
  i18n: {
    strategy: 'prefix',
    detectBrowserLanguage: {
-      // redirectOn: 'root', // ⚠️ In v10 this will only redirect the root path
+      redirectOn: 'all',  // Redirects all paths as documented
    }
  }
})

影响：这影响了使用 strategy: 'prefix' 的项目，这些项目依赖于之前意外的行为，即 redirectOn: 'root' 也处理非根路径。

有关可用选项的更多详细信息，请参见 redirectOn 文档。

I18n 函数

以下组合式函数和 I18n 函数已被更改、弃用或移除。

状态	函数	说明
changed	`useLocaleHead()`	options 参数中的 `key` 属性已被移除，无法再配置，这是为了实现可预测且一致的本地化头部标签管理。
removed	`onLanguageSwitched()`	请使用 `'i18n:localeSwitched'` 钩子替代。该函数实际上是触发钩子而非订阅，导致行为不可预测。
removed	`onBeforeLanguageSwitch()`	请使用 `'i18n:beforeLocaleSwitch'` 钩子替代。该函数实际上是触发钩子而非订阅，导致行为不可预测。

上下文函数

以下上下文函数已被更改、弃用或移除。

状态	函数	说明
changed	`$localeHead()`	options 参数中的 `key` 属性已被移除，无法再配置，这是为了实现可预测且一致的本地化头部标签管理。
deprecated	`$localeHead()`	请改用 `useLocaleHead()` 组合式函数。因使用场景有限已被弃用，且 `useLocaleHead()` 提供相同功能，且与 `useHead()` 配合更易使用。
deprecated	`$getRouteBaseName()`	请使用 `$routeBaseName()` 替代。这是为了与其他上下文函数及其组合式函数名保持一致。
removed	`$resolveRoute()`	请使用 `$localeRoute()` 替代。
removed	`$localeLocation()`	请使用 `$localeRoute()` 替代。