chore!: deprecate $localeHead and rename $getRouteBaseName (#3528)

Co-authored-by: Bobbie Goede <mailto:6649305+BobbieGoede@users.noreply.github.com>

Author: BobbieGoede

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

@@ -10,6 +10,16 @@ We have upgrade from Vue I18n v10 to v11, this major version bump deprecates the
 
 Check the documentation detailing the breaking changes [here](https://vue-i18n.intlify.dev/guide/migration/breaking11.html).
 
+### Deprecate `$localeHead()`{lang="ts"}
+The `$localeHead()`{lang="ts"} Nuxt context function has been deprecated and will be removed in v11. 
+
+This context function has limited use cases, the `useLocaleHead` composable offers the same functionality and is easier to use in combination with `useHead`.
+
+### 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. 
+
+We are renaming this function to `$routeBaseName()`{lang="ts"} to be consistent with the other context functions and their composable counterparts.
+
 ### 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`.
 

docs/content/docs/04.api/05.vue.md

@@ -9,7 +9,7 @@ description: Extension of Vue.
 The APIs listed are available in the Options API. They are kept for Nuxt2 to migration from `@nuxtjs/i18n`. we will be deprecated in the future.
 ::
 
-### `getRouteBaseName()`{lang="ts"}
+### `routeBaseName()`{lang="ts"}
 
 - **Arguments**:
   - route (type: `string | Route`{lang="ts-type"}, default: current route)

docs/content/docs/04.api/06.nuxt.md

@@ -27,7 +27,7 @@ export default defineNuxtPlugin(nuxtApp => {
 })
 ```
 
-### `$getRouteBaseName()`{lang="ts"}
+### `$routeBaseName()`{lang="ts"}
 
 ### `$switchLocalePath()`{lang="ts"}
 

docs/content/docs/06.composables/06.use-route-base-name.md

@@ -17,10 +17,10 @@ declare function useRouteBaseName(
 ```vue
 <script setup>
 const route = useRoute()
-const getRouteBaseName = useRouteBaseName()
-const baseRouteName = computed(() => getRouteBaseName(route))
+const routeBaseName = useRouteBaseName()
+const baseRouteName = computed(() => routeBaseName(route))
 // or
-const baseRouteNameString = computed(() => getRouteBaseName(route.name))
+const baseRouteNameString = computed(() => routeBaseName(route.name))
 </script>
 
 <template>

specs/fixtures/basic_usage/nuxt.config.ts

@@ -1,23 +1,29 @@
 // https://nuxt.com/docs/guide/directory-structure/nuxt.config
 export default defineNuxtConfig({
   modules: ['./layer-module', './installer-module', '@nuxtjs/i18n'],
+
   runtimeConfig: {
     public: {
       runtimeValue: 'Hello from runtime config!',
       longTextTest: false
     }
   },
+
   extends: [
     `../layers/layer-server`,
     `../layers/layer-lazy`,
     `../layers/layer-vueI18n-options/layer-simple`,
     `../layers/layer-vueI18n-options/layer-simple-secondary`
   ],
+
   plugins: [`../plugins/i18nHooks.ts`],
+
   i18n: {
     baseUrl: 'http://localhost:3000',
     vueI18n: './config/i18n.config.ts',
     locales: ['en', 'fr'],
     defaultLocale: 'en'
-  }
+  },
+
+  compatibilityDate: '2025-04-06'
 })

specs/fixtures/basic_usage/pages/nuxt-context-extension.vue

@@ -2,8 +2,8 @@
 
 <template>
   <div>
-    <p id="get-route-base-name">{{ $nuxt.$getRouteBaseName($route) }}</p>
-    <p id="get-route-base-name-string">{{ $nuxt.$getRouteBaseName($route.name) }}</p>
+    <p id="get-route-base-name">{{ $nuxt.$routeBaseName($route) }}</p>
+    <p id="get-route-base-name-string">{{ $nuxt.$routeBaseName($route.name) }}</p>
     <p id="switch-locale-path">{{ $nuxt.$switchLocalePath('ja') }}</p>
     <p id="locale-path">{{ $nuxt.$localePath('nuxt-context-extension', 'nl') }}</p>
     <p id="locale-route">{{ JSON.stringify($nuxt.$localeRoute()) }}</p>

specs/fixtures/basic_usage_compat_4/app/pages/nuxt-context-extension.vue

@@ -2,8 +2,8 @@
 
 <template>
   <div>
-    <p id="get-route-base-name">{{ $nuxt.$getRouteBaseName($route) }}</p>
-    <p id="get-route-base-name-string">{{ $nuxt.$getRouteBaseName($route.name) }}</p>
+    <p id="get-route-base-name">{{ $nuxt.$routeBaseName($route) }}</p>
+    <p id="get-route-base-name-string">{{ $nuxt.$routeBaseName($route.name) }}</p>
     <p id="switch-locale-path">{{ $nuxt.$switchLocalePath('ja') }}</p>
     <p id="locale-path">{{ $nuxt.$localePath('nuxt-context-extension', 'nl') }}</p>
     <p id="locale-route">{{ JSON.stringify($nuxt.$localeRoute()) }}</p>

src/runtime/composables/index.ts

@@ -3,7 +3,7 @@ import { ref } from 'vue'
 import { runtimeDetectBrowserLanguage, wrapComposable } from '../internal'
 import { localeCodes } from '#build/i18n.options.mjs'
 import { _useLocaleHead, _useSetI18nParams } from '../routing/head'
-import { getRouteBaseName, localePath, localeRoute, switchLocalePath } from '../routing/routing'
+import { routeBaseName, localePath, localeRoute, switchLocalePath } from '../routing/routing'
 import type { Ref } from 'vue'
 import type { Locale } from 'vue-i18n'
 import type { I18nHeadMetaInfo, I18nHeadOptions, SeoAttributesOptions } from '#internal-i18n-types'
@@ -13,6 +13,40 @@ import type { RouteLocationGenericPath, I18nRouteMeta } from '../types'
 export * from 'vue-i18n'
 export * from './shared'
 
+declare module '#app' {
+  interface NuxtApp {
+    $localePath: LocalePathFunction
+    $localeRoute: LocaleRouteFunction
+    $routeBaseName: RouteBaseNameFunction
+    $switchLocalePath: SwitchLocalePathFunction
+    /**
+     * @deprecated use {@link useLocaleHead} instead
+     */
+    $localeHead: LocaleHeadFunction
+    /**
+     * @deprecated use {@link $routeBaseName} instead
+     */
+    $getRouteBaseName: RouteBaseNameFunction
+  }
+}
+
+declare module 'vue' {
+  interface ComponentCustomProperties {
+    $localePath: LocalePathFunction
+    $localeRoute: LocaleRouteFunction
+    $routeBaseName: RouteBaseNameFunction
+    $switchLocalePath: SwitchLocalePathFunction
+    /**
+     * @deprecated use {@link useLocaleHead} instead
+     */
+    $localeHead: LocaleHeadFunction
+    /**
+     * @deprecated use {@link $routeBaseName} instead
+     */
+    $getRouteBaseName: RouteBaseNameFunction
+  }
+}
+
 /**
  * Used to set i18n params for the current route.
  *
@@ -82,7 +116,7 @@ export type RouteBaseNameFunction = <Name extends keyof RouteMap = keyof RouteMa
  * Returns a {@link RouteBaseNameFunction} used get the base name of a route.
  */
 export function useRouteBaseName(): RouteBaseNameFunction {
-  return wrapComposable(getRouteBaseName)
+  return wrapComposable(routeBaseName)
 }
 
 /**

src/runtime/plugins/i18n.ts

@@ -29,7 +29,6 @@ import { getDefaultLocaleForDomain, setupMultiDomainLocales } from '../domain'
 import type { Locale, I18nOptions, Composer } from 'vue-i18n'
 import type { NuxtApp } from '#app'
 import type { LocaleObject, I18nPublicRuntimeConfig } from '#internal-i18n-types'
-import type { LocaleHeadFunction } from '../composables'
 
 export default defineNuxtPlugin({
   name: 'i18n:plugin',
@@ -202,17 +201,11 @@ export default defineNuxtPlugin({
      */
     Object.defineProperty(nuxt, '$i18n', { get: () => getI18nTarget(i18n) })
 
-    return {
-      provide: {
-        /**
-         * TODO: remove type assertions while type narrowing based on generated types
-         */
-        localeHead: wrapComposable(localeHead) as LocaleHeadFunction,
-        localePath: useLocalePath(),
-        localeRoute: useLocaleRoute(),
-        getRouteBaseName: useRouteBaseName(),
-        switchLocalePath: useSwitchLocalePath()
-      }
-    }
+    nuxt.provide('localeHead', wrapComposable(localeHead))
+    nuxt.provide('localePath', useLocalePath())
+    nuxt.provide('localeRoute', useLocaleRoute())
+    nuxt.provide('routeBaseName', useRouteBaseName())
+    nuxt.provide('getRouteBaseName', useRouteBaseName())
+    nuxt.provide('switchLocalePath', useSwitchLocalePath())
   }
 })

src/runtime/routing/head.ts

@@ -2,7 +2,7 @@ import { joinURL, withQuery, type QueryValue } from 'ufo'
 import { computed, getCurrentScope, onScopeDispose, ref, unref, useHead, useNuxtApp, watch, type Ref } from '#imports'
 import { assign, isObject, isString } from '@intlify/shared'
 
-import { getRouteBaseName, localeRoute, switchLocalePath } from './routing'
+import { routeBaseName, localeRoute, switchLocalePath } from './routing'
 import { getComposer } from '../compatibility'
 import { toArray } from '../utils'
 import { DYNAMIC_PARAMS_KEY } from '#build/i18n.options.mjs'
@@ -226,10 +226,7 @@ function getHreflangLinks(common: CommonComposableOptions, ctx: HeadContext) {
 
 function getCanonicalUrl(common: CommonComposableOptions, ctx: HeadContext) {
   const route = common.router.currentRoute.value
-  const currentRoute = localeRoute(
-    common,
-    assign({}, route, { path: undefined, name: getRouteBaseName(common, route) })
-  )
+  const currentRoute = localeRoute(common, assign({}, route, { path: undefined, name: routeBaseName(common, route) }))
 
   if (!currentRoute) return ''
 
@@ -245,10 +242,7 @@ function getCanonicalLink(common: CommonComposableOptions, ctx: HeadContext): Me
 
 function getCanonicalQueryParams(common: CommonComposableOptions, ctx: HeadContext) {
   const route = common.router.currentRoute.value
-  const currentRoute = localeRoute(
-    common,
-    assign({}, route, { path: undefined, name: getRouteBaseName(common, route) })
-  )
+  const currentRoute = localeRoute(common, assign({}, route, { path: undefined, name: routeBaseName(common, route) }))
 
   const canonicalQueries = (isObject(ctx.seo) && ctx.seo?.canonicalQueries) || []
   const currentRouteQuery = currentRoute?.query || {}