Migration Guide
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.
| Status | Option | Notes |
|---|---|---|
| promoted | experimental.hmr | Enabled by default and renamed to hmr |
| promoted | experimental.switchLocalePathLinkSSR | Enabled by default and the option to disable it has been removed. |
| promoted | experimental.autoImportTranslationFunctions | Enabled by default and renamed to autoDeclare |
| changed | restructureDir | This can no longer be disabled. We recommend leaving this unset to use the default value of 'i18n'. |
| deprecated | types | Only 'composition' types will be supported in v11, in line with Vue I18n v12. |
| deprecated | baseUrl | Will 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. |
| deprecated | routesNameSeparator | This was documented as internal, use cases for end-users are unclear. |
| deprecated | defaultLocaleRouteNameSuffix | This was documented as internal, use cases for end-users are unclear. |
| removed | lazy | Lazy loading of locale messages is now enabled for all locale files. |
| removed | bundle.optimizeTranslationDirective | This feature has been disabled and fully removed, see the discussion in this issue for context on this change. |
| removed | 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. |
I18n functions
The following composables and I18n functions have been changed, deprecated, or removed.
| Status | Function | Notes |
|---|---|---|
| changed | useLocaleHead() | 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. |
| removed | onLanguageSwitched() | Use the 'i18n:localeSwitched' hook instead.This function actually called the hook instead of subscribing to it, leading to unpredictable behavior. |
| removed | onBeforeLanguageSwitch() | 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.
| Status | Function | Notes |
|---|---|---|
| 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 Name | New 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