Migration Guide

Upgrading from nuxtjs/i18n v7.x

Deprecated vueI18n option to not accept createI18n options

This is to ensure stability and distinction between compile / build-time and runtime since vue-i18n is used in runtime.

For more details please see the GitHub Pull request

You can continue defining vueI18n options in i18n.config. Refer to the Vue i18n and basic usage sections for examples on how to do so.

Change the route key rules in pages option

The key of route set in the pages option has been changed to be file-based relative to the pages/ directory in Nuxt, and excluding the leading /.

The reason is that it is more intuitive to match Nuxt file-based routing.

Nuxt2:

pages/
├── about.vue
├── users/
├──── _id/
├────── profile.vue
├── index.vue

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

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

Deprecated localeLocation()

Use localeRoute instead for the Options API style. The reason for deprecation is due to I/F changes around route resolving in Vue Router.

Deprecated localeLocation() on Nuxt Context APIs

Deprecated for the same reason as the localeLocation() Option API.

Deprecated $nuxtI18nHead()

Use localeHead() instead for the Options API style.

Deprecated nuxtI18n component option

Replaced by the defineI18nRoute() compiler macro as it can be optimized with bundler.

Nuxt2:

<script>
import Vue from 'vue'

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

Nuxt3:

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

Deprecated parsePages option

Use the customRoutes option. because the option name parsePages is not intuitive.

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

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

Deprecated vuex option

Vuex is no longer required by the Nuxt i18n module, use the useSetI18nParams composable to set dynamic route parameters instead.

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

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

For more details, see Lang Switcher.

Deprecated sortRoutes option

This option is no longer necessary since routing in Nuxt 3 no longer requires sorting.

Deprecated skipNuxtState option

This option is no longer necessary as it can be replaced with multiple files lazy loading, which is supported in v8.

Deprecated i18n:extend-messages hook

Replaced by the i18n:registerModule hook, reasoning behind deprecation described below:

• At build-time, the locale resources specified in the nuxt module are pre-compiled to javascript, and those resources are serialized into the runtime context with the nuxt template, which is unsafe.
• Huge locale messages impacted performance.

The alternative i18n:registerModule hook works the same way as lazy loading translations. Only the file information of the locale messages is serialized and passed to the runtime context. The locale messages are loaded by dynamic import and then lazy-loaded, with no negative effect on performance.

For more details see Extending messages hook.

Deprecated vueI18nLoader option

This option is no longer necessary, because i18n custom block is supported by unplugin-vue-i18n as default.

Deprecated onBeforeLanguageSwitch and onLanguageSwitched function options

These functions can now be triggered using Nuxt runtime hooks. Please refer to runtime hooks to see how to use these.

Changed some export APIs name on Nuxt context

The following APIs have been changed to $:

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

Deprecated export APIs in Vuex

Vuex extension APIs were removed, because Vuex no longer required in Nuxt3.

The following APIs are no longer available:

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