nuxtjs/i18n
v9 is still an alpha versionVue 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
optionJIT 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 valueWe now use a default directory structure that is consistent with directory structure changes in Nuxt 4.
What changed
langDir
now defaults to locales
.<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
i18n/
folder in the root directory outside app/
and server/
makes more sense.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
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.
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
The options parameter for useLocaleHead
and $localeHead
as 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.
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 implementationSetting 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.