指南

迁移指南

请遵循本指南将版本从一个主要版本升级到另一个主要版本。

从 `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 文件同时在服务器和客户端使用，在根目录中使用专门的 i18n/ 文件夹更为合理，而不是在 app/ 和 server/ 中。
整洁 - 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() 和更多）的类型和名称未能按预期工作。您可能发现，当不使用前缀（$）时，这些函数仍然可以工作，即使没有从组合式 API 中分配这些函数。

在 v9 中修复了这些类型和名称，如果您在项目中全局使用未带前缀的函数（不使用组合式 API），则需要按照原本的意图为这些函数加上前缀。

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

删除已弃用的 `dynamicRouteParams` 选项和遗留动态路由参数实现

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

组合式 API 的用法类似于已弃用的实现，以下是迁移示例：

<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',
    }
  }
}

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 组合式 API 来设置动态路由参数。

nuxt.config.ts

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

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

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

在构建时，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