15.migrating.md

Migration guide

Follow this guide to upgrade from one major version to the other.

---

Upgrading from nuxtjs/i18n v7.x

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 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

The Reason is same localeLocation() Option API.

Deprecated $nuxtI18nHead()

Use localeHead() instead for Options API style.

Deprecated nuxtI18n component option

Use defineI18nRoute() compiler macro. because 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 customRoutes option. because the option name parsePages is not intuitive.

 export default defineNuxtConfig({
   modules: [
     '@nuxtjs/i18n'
   ],
 
   i18n: {
     // ...
-    parsePages: false,
+    customRoutes: 'config',
     // ...
   }
 })

Deprecated vuex option

Use dynamicRouteParams option. because, vuex no longer requires in Nuxt3.

 export default defineNuxtConfig({
   modules: [
     '@nuxtjs/i18n'
   ],
 
   i18n: {
     // ...
-    vuex: true,
+    dynamicRouteParams: true,
     // ...
   }
 })

About details, See also Lang Switcher.

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.

Change some export APIs name on Nuxt context

The following API will be changed to $:

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

Deprecated export APIs in Vuex

Vuex extention APIs were removed, because Vuex no longer requires in Nuxt3.

The following APIs are no longer available:

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