fix!: deprecate options types, routesNameSeparator, defaultLocaleRouteNameSuffix (#3637)

Author: BobbieGoede

docs/content/docs/02.guide/90.migrating.md

@@ -1,64 +1,86 @@
 ---
 title: Migration Guide
-description: Follow this guide to upgrade from one major version to the other.
+description: Follow this guide to upgrade from v9.x to v10.x
+toc:
+  depth: 3
 ---
 
-## Upgrading from `nuxtjs/i18n` v9.x to v10.x
-
 ### 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](https://vue-i18n.intlify.dev/guide/migration/breaking11.html).
 
-### Lazy load locale messages by default and removed `lazy` option
+### Lazy loading
 The `lazy` option has been removed and lazy loading of locale messages is now the default behavior.
 
-### Function signature corrected for `finalizePendingLocaleChange()`{lang="ts"}
+### `finalizePendingLocaleChange()`{lang="ts"} signature changed
 The function signature for `finalizePendingLocaleChange()`{lang="ts"} has been corrected from `() => Promise<void>`{lang="ts-type"} to `() => void`{lang="ts-type"}.
 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.
 
-### Option default changed `useLocaleHead()`{lang="ts"} and `$localeHead()`{lang="ts"}
+### Default arguments changed `useLocaleHead()`{lang="ts"} and `$localeHead()`{lang="ts"}
 The default value for the `key` property has been changed from `'hid'` to `'key'`.
 
-### Deprecate `$localeHead()`{lang="ts"}
-The `$localeHead()`{lang="ts"} Nuxt context function has been deprecated and will be removed in v11. 
+### `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'`.
+
 
-This context function has limited use cases, the `useLocaleHead` composable offers the same functionality and is easier to use in combination with `useHead`.
+### Removed options
+The following options have been removed:
 
-### Deprecate `$getRouteBaseName()`{lang="ts"} in favor of `$routeBaseName()`{lang="ts"}
-The `$getRouteBaseName()`{lang="ts"} Nuxt context function has been deprecated and will be removed in v11. 
+#### `bundle.optimizeTranslationDirective`{lang="yml"}
+* This feature has been disabled and the option to enable it has been removed, see [the discussion in this issue](https://github.com/nuxt-modules/i18n/issues/3238#issuecomment-2672492536) for context on this change.
 
-We are renaming this function to `$routeBaseName()`{lang="ts"} to be consistent with the other context functions and their composable counterparts.
+#### `experimental.generatedLocaleFilePathFormat`{lang="yml"}
+* File paths (e.g. locale files, vue-i18n configs) configured for this module are now removed from the build entirely making this option obsolete.
 
-### Promote `experimental.autoImportTranslationFunctions` to `autoDeclare`
-This functionality is stable and is now enabled by default, the option has been moved out of the `experimental` configuration object and renamed to `autoDeclare`.
 
-### Promote `experimental.switchLocalePathLinkSSR`
-This functionality is stable and is now enabled by default and the option to enable/disable it has been removed.
+### Deprecated options
+The following options have been deprecated and will be removed in v11:
 
-### Promote `experimental.hmr` to `hmr`
-The HMR functionality is stable, it was already enabled by default but to reflect its stability it has been moved out of the `experimental` configuration object.
+#### `types`{lang="yml"}
+* Only `'composition'` types will be supported in v11, in line with Vue I18n v12.
 
-### Remove `restructureDir` migration path
-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'`.
+#### `routesNameSeparator`{lang="yml"}
+* This was documented as internal, use cases for end-users are unclear.
+
+#### `defaultLocaleRouteNameSuffix`{lang="yml"}
+* 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. 
 
-### Dropped Nuxt context functions
+#### `experimental.hmr`{lang="yml"}
+* Now configurable with the `hmr` option
 
+#### `experimental.switchLocalePathLinkSSR`{lang="yml"}
+* This is stable and the option to enable/disable it has been removed.
+
+#### `experimental.autoImportTranslationFunctions`{lang="yml"}
+* Now configurable with the `autoDeclare` option
+
+
+### Dropped context functions
 The following functions have been removed from the Nuxt context.
-* `$resolveRoute()`{lang="ts"}
-* `$localeLocation()`{lang="ts"}
 
-Steps to migrate
-* `$resolveRoute()`{lang="ts"} -> use `$localeRoute()` instead
-* `$localeLocation()`{lang="ts"} -> use `$localeRoute()` instead
+#### `$resolveRoute()`{lang="ts"}
+* Use `$localeRoute()`{lang="ts"} instead
+
+#### `$localeLocation()`{lang="ts"}
+* Use `$localeRoute()`{lang="ts"} instead
+
+
+### Deprecated context functions
+These Nuxt context functions have been deprecated and will be removed in v11. 
+
+#### `$localeHead()`{lang="ts"}
+* Deprecated due to limited use cases, the `useLocaleHead` composable offers the same functionality and is easier to use in combination with `useHead`.
 
-### Drop `bundle.optimizeTranslationDirective`
-This feature has been disabled and the option to enable it has been removed, see [the discussion in this issue](https://github.com/nuxt-modules/i18n/issues/3238#issuecomment-2672492536) for context on this change.
+#### `$getRouteBaseName()`{lang="ts"}
+* Deprecated in favor of the same function under a new name: `$routeBaseName()`{lang="ts"}, to be consistent with the other context functions and their composable counterparts.
 
-### Drop `experimental.generatedLocaleFilePathFormat`
-File paths (e.g. locale files, vue-i18n configs) configured for this module are now removed entirely making this option obsolete.
 
-### Removed exports from generated options files.
+## 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`):
@@ -75,7 +97,7 @@ 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.
 
-### Removed options from runtime config
+## 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.

src/types.ts

@@ -175,6 +175,10 @@ export type NuxtI18nOptions<
   i18nModules?: { langDir?: string | null; locales?: NuxtI18nOptions<Context>['locales'] }[]
   rootRedirect?: string | RootRedirectOptions
   skipSettingLocaleOnNavigate?: boolean
+  /**
+   * @deprecated This option is deprecated, only `'composition'` types will be supported in the future.
+   * @default 'composition'
+   */
   types?: 'composition' | 'legacy'
   debug?: boolean | 'verbose'
   parallelPlugin?: boolean
@@ -211,13 +215,15 @@ export type NuxtI18nOptions<
   trailingSlash?: boolean
   /**
    * Internal separator used for generated route names for each locale - you shouldn't need to change this
+   * @deprecated This option is deprecated and will be removed in the future.
    * @default '___'
    */
   routesNameSeparator?: string
   /**
    * Internal suffix added to generated route names for default locale
    *
    * Relevant if strategy is `prefix_and_default` - you shouldn't need to change this.
+   * @deprecated This option is deprecated and will be removed in the future.
    * @default 'default'
    */
   defaultLocaleRouteNameSuffix?: string