Migration Guide

Upgrade to Vue I18n v11

We have upgrade from Vue I18n v10 to v11, this major version bump deprecates the Legacy API mode and custom v-t directive and drops tc and $tc from Legacy API mode.

Check the documentation detailing the breaking changes here.

Lazy loading

The lazy option has been removed and lazy loading of locale messages is now the default behavior.

finalizePendingLocaleChange() signature changed

The function signature for finalizePendingLocaleChange() has been corrected from () => Promise<void> to () => void. This change was made since the function does not rely on any async operations and should not be awaited, and should prevent unnecessary function coloring.

Default arguments changed useLocaleHead() and $localeHead()

The default value for the key property has been changed from 'hid' to 'key'.

restructureDir migration path removed

To ease migration in v9 it was possible to disable the new directory structure by setting restructureDir: false, this has now been removed and we recommend using the default value of 'i18n'.

Removed options

The following options have been removed:

bundle.optimizeTranslationDirective

• This feature has been disabled and the option to enable it has been removed, see the discussion in this issue for context on this change.

experimental.generatedLocaleFilePathFormat

• File paths (e.g. locale files, vue-i18n configs) configured for this module are now removed from the build entirely making this option obsolete.

Deprecated options

The following options have been deprecated and will be removed in v11:

types

• Only 'composition' types will be supported in v11, in line with Vue I18n v12.

routesNameSeparator

• This was documented as internal, use cases for end-users are unclear.

defaultLocaleRouteNameSuffix

• This was documented as internal, use cases for end-users are unclear.

Promoted options

These options are stable and are now enabled by default, some have been renamed to better reflect their purpose.

experimental.hmr

• Now configurable with the hmr option

experimental.switchLocalePathLinkSSR

• This is stable and the option to enable/disable it has been removed.

experimental.autoImportTranslationFunctions

• Now configurable with the autoDeclare option

Dropped context functions

The following functions have been removed from the Nuxt context.

$resolveRoute()

• Use $localeRoute() instead

$localeLocation()

• Use $localeRoute() instead

Deprecated context functions

These Nuxt context functions have been deprecated and will be removed in v11.

$localeHead()

• Deprecated due to limited use cases, the useLocaleHead composable offers the same functionality and is easier to use in combination with useHead.

$getRouteBaseName()

• Deprecated in favor of the same function under a new name: $routeBaseName(), to be consistent with the other context functions and their composable counterparts.

Generated options

The generated options files in your projects are meant for internal use by this module at runtime and should never be used, more properties may be removed in the future.

The following exports have been removed from the generated options files (#build/i18n.options.mjs and #internal/i18n/options.mjs):

• nuxtI18nOptions
• NUXT_I18N_MODULE_ID
• parallelPlugin
• isSSG
• hasPages
• DEFAULT_COOKIE_KEY
• DYNAMIC_PARAMS_KEY
• SWITCH_LOCALE_PATH_LINK_IDENTIFIER

Reasons for removal:

• These are no longer used by the module and might expose vulnerable information in the final build
• Some options are now used as static values for better tree-shaking resulting in a smaller project build.

Runtime config

Several options set in the runtime config were only used to transfer build-time configuration to runtime and changing these at runtime could cause issues.

Instead of setting these on runtime config we now treat them as compiler constants, this way we can tree-shake any unused logic from a project build.

The following options have been removed from runtime config:

• defaultDirection
• strategy
  • You can access this on useI18n() or $i18n
• lazy
• routeNameSeparator
• defaultLocaleRouteNameSuffix
• differentDomains
• multiDomainLocales
  • Enabling this requires certain properties on locales at build-time, we do not see the use case for setting this at runtime.
• trailingSlash

Upgrading from earlier versions

The migration guides for v7 and v8 can be found in the legacy documentation