Migration guide

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

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

nuxt.config.js

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

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:

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>

Deprecated `parsePages` option

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

nuxt.config.ts

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

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.