Migration Guide
nuxtjs/i18n
v8.x to v9.x Upgrading from
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.
jit
option Drop
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.
langDir
default value Directory restructure and
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 therestructureDir
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
- Context - i18n files are used both server-side and client-side, using a dedicated
i18n/
folder in the root directory outsideapp/
andserver/
makes more sense. - 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.
iso
renamed to language
Locale
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.
v8 | v9 | Notes |
---|---|---|
locales | domainLocales | This also changes the environment variable key to NUXT_PUBLIC_I18N_DOMAIN_LOCALES_{code}_DOMAIN , see runtimeConfig |
configLocales | locales |
useLocaleHead()
SEO -
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:
v8 | v9 | Notes |
---|---|---|
- | lang | New property to configure the lang html attributes, default: true |
addDirAttributes | dir | Default changed: false -> true |
addSeoAttributes | seo | Default changed: false -> true |
identifierAttribute | key |
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()
dynamicRouteParams
option and legacy dynamic route parameters implementation Removal of deprecated
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.
nuxtjs/i18n
v7.x to v8.x Upgrading from
vueI18n
option to not accept createI18n
options Deprecated
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.
pages
option Change the route key rules in
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',
}
}
}
localeLocation()
Deprecated
Use localeRoute
instead for the Options API style. The reason for deprecation is due to I/F changes around route resolving in Vue Router.
localeLocation()
on Nuxt Context APIs Deprecated
Deprecated for the same reason as the localeLocation()
Option API.
$nuxtI18nHead()
Deprecated
Use localeHead()
instead for the Options API style.
nuxtI18n
component option Deprecated
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>
parsePages
option Deprecated
Use the customRoutes
option. because the option name parsePages
is not intuitive.
export default defineNuxtConfig({
modules: [
'@nuxtjs/i18n'
],
i18n: {
// ...
- parsePages: false,
+ customRoutes: 'config',
// ...
}
})
vuex
option Deprecated
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.
sortRoutes
option Deprecated
This option is no longer necessary since routing in Nuxt 3 no longer requires sorting.
skipNuxtState
option Deprecated
This option is no longer necessary as it can be replaced with multiple files lazy loading, which is supported in v8.
i18n:extend-messages
hook Deprecated
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.
vueI18nLoader
option Deprecated
This option is no longer necessary, because i18n custom block is supported by unplugin-vue-i18n as default.
onBeforeLanguageSwitch
and onLanguageSwitched
function options Deprecated
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()