Migration Guide

Upgrading from nuxtjs/i18n v8.x to v9.x

Upgrade to Vue I18n v10

Vue I18n has been upgraded from v9 to v10. Vue I18n v10 has no major feature additions, but there are some disruptive changes, such as dropping some features that were deprecated in v9 and integrating the API $tc() into $t(), which can be used in the Legacy API style

Check the documentation here for more information.

Drop jit option

JIT compilation is now the default in Vue I18n v10.

https://vue-i18n.intlify.dev/guide/migration/breaking10.html#default-enable-for-jit-compilation

Accordingly, the jit option in Nuxt I18n v8 is no longer needed, so this option has been removed.

Directory restructure and langDir default value

We now use a default directory structure that is consistent with directory structure changes in Nuxt 4.

What changed

• langDir now defaults to 'locales'.
• All i18n files are resolved relative to <rootDir>/i18n, this can be configured with the restructureDir option.

Here is an example of a project structure after this change:

app/
server/
i18n/
  locales/
    en.json
    ja.json
  i18n.config.ts
  localeDetector.ts
nuxt.config.ts

Reasons for change

1. Context - i18n files are used both server-side and client-side, using a dedicated i18n/ folder in the root directory outside app/ and server/ makes more sense.
2. Clean - less clutter/fragmentation of i18n files, and should make resolving and loading files easier for us.

To ease the migration to v9 you can disable this feature by setting restructureDir: false, this will be removed in v10.

Locale iso renamed to language

The iso property on a locale object has been renamed to language to be consistent with the usage of Language Tags on the web (e.g. navigator.language and Accept-Language). The original iso property name referred to ISO standards which describe valid Language Tags, see the related issue for more details.

Runtime config properties

Some properties have changed or swapped names to better fit their functionality, the runtime config properties configured by this module are mostly used for internal purposes and should not be relied upon but it's worth noting these changes.

SEO - useLocaleHead()

The options parameter for useLocaleHead() and $localeHead() has changed in shape, having less verbose property names, as well as enabling the options by default.

This table compares the option properties of useLocaleHead() and $localeHead() for v8 and v9:

We have added a lang property to the options parameter of useLocaleHead() and $localeHead(), originally this was not configurable on its own, see useLocaleHead() for details on its usage.

Nuxt context functions

In v8 both the types and name of the injected context functions (such as $localePath(), $switchLocalePath() and more) did not work as intended. You may have found that these functions worked when using them without prefix ($) even when not assigning these functions from a composable.

The types and names have been fixed in v9, if you have been using the unprefixed functions globally (without composable) in your project you will have to prefix these functions as they were originally intended.

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

Removal of deprecated dynamicRouteParams option and legacy dynamic route parameters implementation

Setting dynamic route parameters by setting the nuxtI18n property with definePageMeta() has been fully removed in favor of the useSetI18nParams() composable, this feature is enabled by default which means the dynamicRouteParams option is no longer necessary.

The composable usage is similar to that of the deprecated implementation, see the migration example below:

<script>
definePageMeta({
  nuxtI18n: {
    en: { id: 'my-post' },
    fr: { id: 'mon-article' }
  }
})
</script>
<template>
  <!-- pages/post/[id].vue -->
</template>

Should be changed to:

<script>
const setI18nParams = useSetI18nParams();
setI18nParams({
    en: { id: 'my-post' },
    fr: { id: 'mon-article' }
})
</script>
<template>
  <!-- pages/post/[id].vue -->
</template>

Check out the Lang Switcher guide for more details.

Upgrading from nuxtjs/i18n v7.x to v8.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()