迁移指南

从 `nuxtjs/i18n` v8.x 升级到 v9.x

升级到 Vue I18n v10

Vue I18n 已从 v9 升级到 v10。Vue I18n v10 没有新增重大功能，但有一些破坏性的变化，例如删除了在 v9 中被弃用的某些功能，并将 API $tc() 集成到 $t() 中，可以在旧版 API 风格中使用。

更多信息，请查看文档这里。

删除 `jit` 选项

JIT 编译现在是 Vue I18n v10 的默认选项。

https://vue-i18n.intlify.dev/guide/migration/breaking10.html#default-enable-for-jit-compilation

因此，在 Nuxt I18n v8 中的 jit 选项不再需要，因此已被删除。

目录重构及 `langDir` 默认值

我们现在使用与 Nuxt 4 中的目录结构变更一致的默认目录结构。

变更内容：

langDir 现在默认为 'locales'。
所有 i18n 文件相对于 <rootDir>/i18n 解决，可以使用 restructureDir 选项进行配置。

以下是此更改后的项目结构示例：

app/
server/
i18n/
  locales/
    en.json
    ja.json
  i18n.config.ts
  localeDetector.ts
nuxt.config.ts

变更原因：

上下文 - i18n 文件在服务器端和客户端都使用，在 app/ 和 server/ 外面的根目录使用专用的 i18n/ 文件夹更为合理。
整洁 - 减少 i18n 文件的杂乱和碎片化，应该使文件的解析和加载对我们来说更容易。

为了便于迁移到 v9，您可以通过设置 restructureDir: false 来禁用该功能，此选项将在 v10 中被移除。

语言环境的 `iso` 重命名为 `language`

语言环境对象上的 iso 属性已重命名为 language，以与网页上的语言标签使用一致（例如 navigator.language 和 Accept-Language）。原来的 iso 属性名称指的是描述有效语言标签的 ISO 标准，详情请参见相关问题。

运行时配置属性

一些属性已更改名称或互换，以更好地符合其功能。本模块配置的运行时配置属性主要用于内部目的，不应依赖，但值得注意的是这些变化。

v8	v9	备注
`locales`	`domainLocales`	这还将环境变量键更改为 `NUXT_PUBLIC_I18N_DOMAIN_LOCALES_{code}_DOMAIN`，请参见 `runtimeConfig`
`configLocales`	`locales`

SEO - `useLocaleHead()`

useLocaleHead() 和 $localeHead() 的选项参数的结构已更改，具有更简洁的属性名称，并且默认启用这些选项。

以下表格比较了 v8 和 v9 中 useLocaleHead() 和 $localeHead() 的选项属性：

v8	v9	备注
`-`	`lang`	新属性，用于配置 `lang` HTML 属性，默认为 `true`
`addDirAttributes`	`dir`	默认已更改：`false` -> `true`
`addSeoAttributes`	`seo`	默认已更改：`false` -> `true`
`identifierAttribute`	`key`

我们在 useLocaleHead() 和 $localeHead() 的选项参数中添加了 lang 属性，原本这个属性是不可单独配置的，详情请参见 useLocaleHead()。

Nuxt 上下文函数

在 v8 中，注入的上下文函数（例如 $localePath(), $switchLocalePath() 等）类型和名称未能如预期工作。即使未从组合函数赋值，这些函数在使用时可能也会发现它们可以不带前缀（$）使用。

在 v9 中，类型和名称已被修复，如果您在项目中全局使用未加前缀的函数（没有组合函数），您需要按照原本的意图为这些函数添加前缀。

getRouteBaseName() -> $getRouteBaseName()
resolveRoute() -> $resolveRoute()
localePath() -> $localePath()
localeRoute() -> $localeRoute()
localeLocation() -> $localeLocation()
switchLocalePath() -> $switchLocalePath()
localeHead() -> $localeHead()

移除弃用的 `dynamicRouteParams` 选项及遗留动态路由参数实现

通过设置 nuxtI18n 属性与 definePageMeta() 设置动态路由参数的功能已被完全移除，取而代之的是 useSetI18nParams() 组合函数，该功能默认启用，这意味着 dynamicRouteParams 选项不再必要。

组合函数的用法与弃用的实现类似，以下是迁移示例：

<script>
definePageMeta({
  nuxtI18n: {
    en: { id: 'my-post' },
    fr: { id: 'mon-article' }
  }
})
</script>
<template>
  <!-- pages/post/[id].vue -->
</template>

应更改为：

<script>
const setI18nParams = useSetI18nParams();
setI18nParams({
    en: { id: 'my-post' },
    fr: { id: 'mon-article' }
})
</script>
<template>
  <!-- pages/post/[id].vue -->
</template>

有关更多详细信息，请查看语言切换器指南。

从 `nuxtjs/i18n` v7.x 升级到 v8.x

弃用 `vueI18n` 选项以不接受 `createI18n` 选项

这是为了确保编译/构建时与运行时之间的稳定性和区分，因为 vue-i18n 在运行时被使用。

更多详细信息请参见 GitHub 拉取请求。

您可以继续在 i18n.config 中定义 vueI18n 选项。有关如何操作的示例，请参见 Vue i18n 和基本使用部分。

更改 `pages` 选项中的路由键规则

在 pages 选项中设置的路由键已变更为相对于 Nuxt 中的 pages/ 目录的文件基础，并且 不包括前导 /。

原因是这与 Nuxt 基于文件的路由匹配更为直观。

Nuxt2:

-| pages/
---| about.vue
---| users/
-----| _id/
-------| profile.vue
---| index.vue

nuxt.config.ts

i18n: {
  parsePages: false,
  pages: {
    about: {
      fr: '/a-propos',
    },
    'users/_id/profile': {
      fr: '/u/:id/profil',
    }
  }
}

Nuxt3:

pages/
├── about.vue
├── users/
├──── [id]/
├────── profile.vue
├── index.vue

nuxt.config.ts

i18n: {
  customRoutes: 'config',
  pages: {
    about: {
      fr: '/a-propos',
    },
    'users/[id]/profile': {
      fr: '/u/[id]/profil',
    }
  }
}

弃用 `localeLocation()`

对于选项 API 风格，请使用 localeRoute 代替。弃用的原因是关于 Vue Router 中路由解析的接口更改。

在 Nuxt 上下文 API 中弃用 `localeLocation()`

由于与 localeLocation() 选项 API 的同样原因而被弃用。

弃用 `$nuxtI18nHead()`

对于选项 API 风格，请使用 localeHead() 代替。

弃用 `nuxtI18n` 组件选项

已被 defineI18nRoute() 编译宏替代，因为它可以与打包器优化。

Nuxt2:

pages/about.vue

<script>
import Vue from 'vue'

export default Vue.extend({
  nuxtI18n: {
    paths: {
      pl: '/polish'
    }
  }
})
</script>

Nuxt3:

pages/about.vue

<script setup>
defineI18nRoute({
  paths: {
    pl: '/polish'
  }
})
</script>

弃用 `parsePages` 选项

使用 customRoutes 选项。因为选项名称 parsePages 并不直观。

nuxt.config.ts

 export default defineNuxtConfig({
   modules: [
     '@nuxtjs/i18n'
   ],

   i18n: {
     // ...
-    parsePages: false,
+    customRoutes: 'config',
     // ...
   }
 })

弃用 `vuex` 选项

Nuxt i18n 模块不再需要 Vuex，请使用 useSetI18nParams 组合函数代替以设置动态路由参数。

nuxt.config.ts

 export default defineNuxtConfig({
   modules: [
     '@nuxtjs/i18n'
   ],

   i18n: {
     // ...
-    vuex: true,
     // ...
   }
 })

有关更多详细信息，请参见语言切换器。

弃用 `sortRoutes` 选项

此选项不再需要，因为 Nuxt 3 中的路由不再需要排序。

弃用 `skipNuxtState` 选项

此选项不再需要，因为它可以用多文件懒加载替代，该功能在 v8 中得到支持。

弃用 `i18n:extend-messages` 钩子

被 i18n:registerModule 钩子所替代，弃用原因如下：

在构建时，指定在 Nuxt 模块中的语言环境资源会被预编译为 JavaScript，并且这些资源在运行时上下文中与 Nuxt 模板序列化，这是不安全的。
巨大的语言环境消息会影响性能。

替代的 i18n:registerModule 钩子与懒加载翻译的工作方式相同。只有语言环境消息的文件信息被序列化并传递到运行时上下文。语言环境消息通过动态导入加载，然后懒加载，在性能上没有负面影响。

有关更多详细信息，请参见扩展消息钩子。

i18n -> $i18n
getRouteBaseName() -> $getRouteBaseName()
localePath() -> $localePath()
localeRoute() -> $localeRoute()
switchLocalePath() -> $switchLocalePath()

在 Vuex 中弃用导出 API

Vuex 扩展 API 已被移除，因为在 Nuxt3 中不再需要 Vuex。

以下 API 不再可用：

$i18n
getRouteBaseName()
localePath()
localeRoute()
localeLocation()
switchLocalePath()

通过模块安装

如何通过模块内部的 `installModule` 安装 Nuxt i18n。

选项

所有可用于配置 Nuxt I18n 的选项。

从 `nuxtjs/i18n` v8.x 升级到 v9.x

升级到 Vue I18n v10

删除 `jit` 选项

目录重构及 `langDir` 默认值

语言环境的 `iso` 重命名为 `language`

运行时配置属性

SEO - `useLocaleHead()`

Nuxt 上下文函数

移除弃用的 `dynamicRouteParams` 选项及遗留动态路由参数实现

从 `nuxtjs/i18n` v7.x 升级到 v8.x

弃用 `vueI18n` 选项以不接受 `createI18n` 选项

更改 `pages` 选项中的路由键规则

弃用 `localeLocation()`

在 Nuxt 上下文 API 中弃用 `localeLocation()`

弃用 `$nuxtI18nHead()`

弃用 `nuxtI18n` 组件选项

弃用 `parsePages` 选项

弃用 `vuex` 选项

弃用 `sortRoutes` 选项

弃用 `skipNuxtState` 选项

弃用 `i18n:extend-messages` 钩子

弃用 `vueI18nLoader` 选项

弃用 `onBeforeLanguageSwitch` 和 `onLanguageSwitched` 函数选项

更改 Nuxt 上下文中一些导出 API 的名称

在 Vuex 中弃用导出 API