Guide

Migration Guide

Follow this guide to upgrade from v9.x to v10.x

Upgraded to Vue I18n v11

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

Check the documentation detailing the breaking changes here.

Configuration options

The following Configuration options have been changed, deprecated, or removed.

StatusOptionNotes
promotedexperimental.hmrEnabled by default and renamed to hmr
promotedexperimental.switchLocalePathLinkSSREnabled by default and the option to disable it has been removed.
promotedexperimental.autoImportTranslationFunctionsEnabled by default and renamed to autoDeclare
changedrestructureDirThis can no longer be disabled.

We recommend leaving this unset to use the default value of 'i18n'.
deprecatedtypesOnly 'composition' types will be supported in v11, in line with Vue I18n v12.
deprecatedbaseUrlWill only allow string values and will no longer support function configuration in v11.

Use runtime config or rely on multi domain locales to set the base URL for complex setups.
deprecatedroutesNameSeparatorThis was documented as internal, use cases for end-users are unclear.
deprecateddefaultLocaleRouteNameSuffixThis was documented as internal, use cases for end-users are unclear.
removedlazyLazy loading of locale messages is now enabled for all locale files.
removedbundle.optimizeTranslationDirectiveThis feature has been disabled and fully removed, see the discussion in this issue for context on this change.
removedexperimental.generatedLocaleFilePathFormatFile paths (e.g. locale files, vue-i18n configs) configured for this module are now removed from the build entirely making this option obsolete.

I18n functions

The following composables and I18n functions have been changed, deprecated, or removed.

StatusFunctionNotes
changeduseLocaleHead()The key property on the options parameter has been removed and can no longer be configured, this is necessary for predictable and consistent localized head tag management.
removedonLanguageSwitched()Use the 'i18n:localeSwitched' hook instead.

This function actually called the hook instead of subscribing to it, leading to unpredictable behavior.
removedonBeforeLanguageSwitch()Use the 'i18n:beforeLocaleSwitch' hook instead.

This function actually called the hook instead of subscribing to it, leading to unpredictable behavior.

Context functions

The following context functions have been changed, deprecated, or removed.

StatusFunctionNotes
changed$localeHead()The key property on the options parameter has been removed and can no longer be configured, this is necessary for predictable and consistent localized head tag management.
deprecated$localeHead()Use the useLocaleHead() composable instead.

Deprecated due to limited use cases, the useLocaleHead() composable offers the same functionality and is easier to use in combination with useHead().
deprecated$getRouteBaseName()Use $routeBaseName() instead.

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

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:

Removed runtime config option
lazy
strategy
trailingSlash
differentDomains
defaultDirection
multiDomainLocales
routeNameSeparator
defaultLocaleRouteNameSuffix

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.

-Future changes to these internal options will not be documented in the migration guide. If you have use cases for these options, please open an issue describing your use case so we can evaluate if we can support it in a different way. +Future changes to these internal options will not be documented in the migration guide. If you have use cases for these options, please open an issue describing your use case so we can evaluate if we can support it differently.

The generated option files have been renamed:

Old NameNew Name
#build/i18n-options.mjs#build/i18n-options.mjs
#internal/i18n/options.mjs#internal/i18n-options.mjs

The following exports have been removed from the generated options:

Removed Export
isSSG
hasPages
parallelPlugin
nuxtI18nOptions
DEFAULT_COOKIE_KEY
DYNAMIC_PARAMS_KEY
NUXT_I18N_MODULE_ID
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.

Legacy migration

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