迁移指南

从一个主版本升级到另一个主版本的指南。

从 nuxt-i18n 升级到 @nuxtjs/i18n

总结：

模块名称从 nuxt-i18n 更改为 @nuxtjs/i18n

卸载旧模块并安装新模块：

npx nuxi@latest module add i18n

在 nuxt.config.js 中更改模块名称：

  modules: [
-    'nuxt-i18n'
+    '@nuxtjs/i18n'
  ]
  • 更新代码中可能存在的其他对旧名称的引用。

beforeLanguageSwitch 替换为 onBeforeLanguageSwitch

如果您在模块配置中或通过 API 定义了 beforeLanguageSwitch 选项，那么您需要切换到 onBeforeLanguageSwitch。

示例更改：

-  app.i18n.beforeLanguageSwitch = (oldLocale, newLocale) => {
-    // ...
-  }
+  app.i18n.onBeforeLanguageSwitch = (oldLocale, newLocale, isInitialSetup, context) => {
+    if (!isInitialSetup) {
+      // ...
+    }
+  }

请注意，旧的钩子在“初始设置”情况下不会被调用，因此为了保留旧行为，当 isInitialSetup 为 true 时，您可能希望跳过运行您的钩子代码。

另请查看 onBeforeLanguageSwitch 文档。

NuxtVueI18n TypeScript 命名空间已被移除

模块不再定义或导出全局的 NuxtVueI18n TypeScript 命名空间。现在所有模块类型都直接导出，不通过全局命名空间提供。

如果您在 TypeScript 代码中或在 JavaScript 代码中的 JSDoc 注释中使用了来自全局命名空间的类型，则必须从 @nuxtjs/i18n 模块显式导入该类型。

例如，替换以下内容：

/** @type {NuxtVueI18n.LocaleObject} */
const locale = { code: 'en' }

改为：

/** @type {import('@nuxtjs/i18n').LocaleObject} */
const locale = { code: 'en' }

导出类型的名称在某些情况下也发生了变化，请参考 /types/index.d.ts 文件以查看导出的类型。

seo 选项已被移除

出于性能原因，模块选项 seo 已被移除。

替代方案是在布局文件的 head 组件选项中返回 $nuxtI18nHead({ addDirAttribute: true, addSeoAttributes: true })。

有关更多详细信息，请参见 SEO 指南。

$nuxtI18nSeo 已被移除

用于生成将在 Nuxt 的 head 组件选项中使用的元信息的 $nuxtI18nSeo() 函数已被移除。

如果您在代码中使用过 $nuxtI18nSeo，请将其替换为 $nuxtI18nHead({ addSeoAttributes: true })。

另请参见 SEO 指南 和 $nuxtI18nHead API 文档。

$nuxtI18nHead 的 addDirAttribute 选项默认值已从 true 更改为 false

$nuxtI18nHead 接受的 addDirAttribute 选项的默认值已从 true 更改为 false。

如果您没有设置 defaultDirection 模块选项，也没有在您的地区定义 dir 属性，则不需要做任何事情。否则，如果您使用 $nuxtI18nHead，则需要显式启用 addDirAttribute，方法是 $nuxtI18nHead({ addDirAttribute: true })。

onlyOnRoot 和 onlyOnNoPrefix 选项已被移除

已移除的 detectBrowserLanguage.onlyOnRoot 和 detectBrowserLanguage.onlyOnNoPrefix 选项现在合并为单个 detectBrowserLanguage.redirectOn 选项，该选项接受值 'all'、'root' 或 'no prefix'。

如果您显式启用了 onlyOnRoot 或 onlyOnNoPrefix 选项，请分别切换为 redirectOn: 'root' 或 redirectOn: 'no prefix'。

请注意，默认值也已从 all 更改为 root。

另请参见 detectBrowserLanguage 文档。

detectBrowserLanguage 默认情况下仅在根路径触发

之前，启用 detectBrowserLanguage 后，模块会尝试根据访问的路径检测浏览器的语言环境。现在默认情况下不再如此 - 该模块将仅在访问根路径时尝试重定向。

为了更好的 SEO，建议保持新行为启用，但如果您希望恢复到先前的行为，则将 redirectOn 设置为 'all'。

另请参见 浏览器语言检测指南。

Vuex 的 syncLocale 和 syncMessages 属性已被移除

已移除 vuex 模块选项 syncLocale 和 syncMessages。

我们决定这些选项是多余的，因为可以通过 API 以另一种方式访问它们：

  • 当前使用的语言环境可以通过 $i18n.locale 访问
  • 当前加载的消息可以通过 $i18n.messages 访问

扩展消息钩子

API 参考