feat: support custom routes via definePageMeta (#3578)

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

Author: BobbieGoede

docs/content/docs/02.guide/03.custom-paths.md

@@ -3,7 +3,7 @@ title: Custom Route Paths
 description: Customize the names of the paths for specific locale.
 ---
 
-In some cases, you might want to translate URLs in addition to having them prefixed with the locale code. There are two methods of configuring custom paths, through [Module configuration](#module-configuration) or from within each [Page component](#page-component).
+In some cases, you might want to translate URLs in addition to having them prefixed with the locale code. There are two methods of configuring custom paths, through [Module configuration](#module-configuration) or from within each [Page component](#definepagemeta).
 
 Which method is used is configured by setting the [`customRoutes` options](/docs/api/options#customroutes) this is set to `'page'`{lang="ts-type"} by default. Using both methods at the same time is not possible.
 
@@ -183,17 +183,47 @@ export default defineNuxtConfig({
 })
 ```
 
-## Page component
+## `definePageMeta`
+
+You can use the `i18n` property in `definePageMeta()`{lang="ts"} to set custom paths for each page component.
+```vue [pages/about.vue]
+<script setup>
+definePageMeta({
+  i18n: {
+    paths: {
+      en: '/about-us', // -> accessible at /about-us (no prefix since it's the default locale)
+      fr: '/a-propos', // -> accessible at /fr/a-propos
+      es: '/sobre' // -> accessible at /es/sobre
+    }
+  }
+})
+</script>
+```
+
+To configure a custom path for a dynamic route, you need to use it in double square brackets in the paths similar to how you would do it in [Nuxt Dynamic Routes](https://nuxt.com/docs/guide/directory-structure/pages#dynamic-routes):
+
+```vue [pages/articles/[name].vue]
+<script setup>
+definePageMeta({
+  i18n: {
+    paths: {
+      en: '/articles/[name]',
+      es: '/artículo/[name]'
+    }
+  }
+})
+</script>
+```
+
+## `defineI18nRoute`
 
 ::callout{icon="i-heroicons-exclamation-triangle" color="warning" title="notice"}
-Note for those updating to `v8.0.1`{lang="sh"} or higher
-:br :br
-Path parameters parsing has been changed to match that of [Nuxt 3](https://nuxt.com/docs/guide/directory-structure/pages#dynamic-routes), you will have to update your custom paths (e.g. `'/example/:param'`{lang="ts-type"} should now be `'/example/[param]'`{lang="ts-type"})
+This method is deprecated in favor of `definePageMeta()`{lang="ts"} and will be removed in v11.
 ::
 
 You can use the `defineI18nRoute()`{lang="ts"} compiler macro to set custom paths for each page component.
 
-```vue {}[pages/about.vue]
+```vue [pages/about.vue]
 <script setup>
 defineI18nRoute({
   paths: {
@@ -205,9 +235,9 @@ defineI18nRoute({
 </script>
 ```
 
-To configure a custom path for a dynamic route, you need to use it in double square brackets in the paths similarly to how you would do it in [Nuxt Dynamic Routes](https://nuxt.com/docs/guide/directory-structure/pages#dynamic-routes):
+To configure a custom path for a dynamic route, you need to use it in double square brackets in the paths similar to how you would do it in [Nuxt Dynamic Routes](https://nuxt.com/docs/guide/directory-structure/pages#dynamic-routes):
 
-```vue {}[pages/articles/[name].vue]
+```vue [pages/articles/[name].vue]
 <script setup>
 defineI18nRoute({
   paths: {

docs/content/docs/02.guide/04.ignoring-localized-routes.md

@@ -13,7 +13,17 @@ If you'd like some pages to be available in some languages only, you can configu
 
 ::code-group
 
-```vue [pages/about.vue]
+```vue [about-meta.vue]
+// pages/about.vue
+<script setup>
+definePageMeta({
+  i18n: { locales: ['fr', 'es'] }
+})
+</script>
+```
+
+```vue [about-macro.vue]
+// pages/about.vue
 <script setup>
 defineI18nRoute({
   locales: ['fr', 'es']
@@ -37,7 +47,15 @@ i18n: {
 
 ::code-group
 
-```vue [pages/about.vue]
+```vue [about-meta.vue]
+// pages/about.vue
+<script setup>
+definePageMeta({ i18n: false })
+</script>
+```
+
+```vue [about-macro.vue]
+// pages/about.vue
 <script setup>
 defineI18nRoute(false)
 </script>

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

@@ -10,10 +10,29 @@ 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).
 
+### Custom routes via `definePageMeta()`{lang="ts"}
+We have added support for setting custom routes for pages using the `definePageMeta()`{lang="ts"} API, which is now the recommended way to set custom routes for pages.
+This method is enabled by setting `customRoutes: 'meta'`{lang="ts"} in the module options.
+
+To migrate from the `defineI18nRoute()`{lang="ts"} macro, you can simply replace it with `definePageMeta()`{lang="ts"} and set the `i18n` property with the same options:
+```vue [pages/about.vue]
+<script setup>
+definePageMeta({
+  i18n: {
+    paths: {
+      en: '/about-us',
+      fr: '/a-propos',
+    }
+  }
+})
+</script>
+```
+
+
 ### Lazy loading
 The `lazy` option has been removed and lazy loading of locale messages is now the default behavior.
 
-### `finalizePendingLocaleChange()`{lang="ts"} signature changed
+### Signature changed for `finalizePendingLocaleChange()`{lang="ts"}
 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.
 

docs/content/docs/04.api/00.options.md

@@ -183,10 +183,14 @@ Routes generation strategy. Can be set to one of the following:
 
 ## customRoutes
 
-- type: `'page' | 'config'`{lang="ts-type"}
+- type: `'meta' | 'page' | 'config'`{lang="ts-type"}
 - default: `'page'`{lang="ts-type"}
 
-Whether [custom paths](/docs/guide/custom-paths) are extracted from page files
+Whether [custom paths](/docs/guide/custom-paths) are extracted from page files or configured in the module configuration:
+
+- `'meta'`{lang="ts-type"}: custom paths are extracted from the `definePageMeta()`{lang="ts"} function in page components.
+- `'page'`{lang="ts-type"}: custom paths are extracted from the `defineI18nRoute()`{lang="ts"} macro in page components.
+- `'config'`{lang="ts-type"}: custom paths are configured in the `pages` option of the module configuration.
 
 ## pages
 

specs/fixtures/basic_usage/pages/about/index.vue

@@ -13,16 +13,6 @@ const code = computed(() => {
 definePageMeta({
   title: 'about'
 })
-
-/*
-// TODO: defineNuxtI18n macro
-defineNuxtI18n({
-  paths: {
-    en: '/about-us',
-    fr: '/a-propos'
-  }
-})
-*/
 </script>
 
 <template>

specs/fixtures/basic_usage_compat_4/app/pages/about/index.vue

@@ -13,16 +13,6 @@ const code = computed(() => {
 definePageMeta({
   title: 'about'
 })
-
-/*
-// TODO: defineNuxtI18n macro
-defineNuxtI18n({
-  paths: {
-    en: '/about-us',
-    fr: '/a-propos'
-  }
-})
-*/
 </script>
 
 <template>

specs/fixtures/lazy/pages/about/index.vue

@@ -8,16 +8,6 @@ const localePath = useLocalePath()
 const code = computed(() => {
   return localeProperties.value.code
 })
-
-/*
-// TODO: defineNuxtI18n macro
-defineNuxtI18n({
-  paths: {
-    en: '/about-us',
-    fr: '/a-propos'
-  }
-})
-*/
 </script>
 
 <template>

specs/fixtures/restructure/pages/about/index.vue

@@ -8,16 +8,6 @@ const localePath = useLocalePath()
 const code = computed(() => {
   return localeProperties.value.code
 })
-
-/*
-// TODO: defineNuxtI18n macro
-defineNuxtI18n({
-  paths: {
-    en: '/about-us',
-    fr: '/a-propos'
-  }
-})
-*/
 </script>
 
 <template>

src/gen.ts

@@ -3,6 +3,7 @@ import { genDynamicImport, genSafeVariableName, genString } from 'knitwork'
 import { resolve, relative, join, basename } from 'pathe'
 import { getLayerI18n } from './utils'
 import { asI18nVirtual } from './transform/utils'
+import { resolveModule } from '@nuxt/kit'
 
 import type { Nuxt } from '@nuxt/schema'
 import type { NuxtI18nOptions, LocaleObject } from './types'
@@ -199,6 +200,7 @@ import type { Strategies, Directions, LocaleObject } from '${relative(
     join(nuxt.options.buildDir, 'types'),
     resolve(distDir, 'types.d.mts')
   )}'
+import type { I18nRoute } from '#i18n'
 
 declare module 'vue-i18n' {
   interface ComposerCustom extends ComposerCustomProperties<${resolvedLocaleType}> {}
@@ -214,10 +216,25 @@ declare module '@intlify/core-base' {
   }
 }
 
+interface I18nMeta {
+  i18n?: I18nRoute | false
+}
+
 declare module '#app' {
   interface NuxtApp {
     $i18n: ${i18nType}
   }
+  interface PageMeta extends I18nMeta {}
+}
+
+
+// NOTE: this is a workaround for Nuxt <3.16.2
+declare module '${resolve(resolveModule('nuxt'), '../pages/runtime/composables')}' {
+  interface PageMeta extends I18nMeta {}
+}
+
+declare module 'vue-router' {
+  interface RouteMeta extends I18nMeta {}
 }
 
 ${typedRouterAugmentations}

src/pages.ts

@@ -19,6 +19,7 @@ import type { EditableTreeNode, Options as TypedRouterOptions } from 'unplugin-v
 import type { NuxtI18nOptions } from './types'
 import type { I18nNuxtContext } from './context'
 import type { ComputedRouteOptions, RouteOptionsResolver } from './kit/gen'
+import type { I18nRoute } from './runtime/composables'
 
 const debug = createDebug('@nuxtjs/i18n:pages')
 
@@ -55,6 +56,9 @@ export async function setupPages({ localeCodes, options }: I18nNuxtContext, nuxt
 
   const projectLayer = nuxt.options._layers[0]
   const typedRouter = await setupExperimentalTypedRoutes(options, nuxt)
+
+  nuxt.options.experimental.extraPageMetaExtractionKeys ??= []
+  nuxt.options.experimental.extraPageMetaExtractionKeys.push('i18n')
   nuxt.hook(
     nuxt.options.experimental.scanPageMeta === 'after-resolve' ? 'pages:resolved' : 'pages:extend',
     async pages => {
@@ -296,15 +300,34 @@ function getRouteFromMacro(
   }
 }
 
+function getRouteFromMeta(
+  _ctx: NuxtPageAnalyzeContext,
+  route: NuxtPage,
+  localeCodes: string[]
+): ComputedRouteOptions | false | undefined {
+  const resolved = route.meta?.i18n as I18nRoute | false | undefined
+  if (!resolved) return resolved
+  return {
+    paths: (resolved.paths ?? {}) as Record<string, string>,
+    locales: resolved?.locales || localeCodes
+  }
+}
+
 function getRouteOptions(
   route: NuxtPage,
   localeCodes: string[],
   ctx: NuxtPageAnalyzeContext,
   defaultLocale: string,
-  mode: 'config' | 'page' = 'config'
+  mode: 'config' | 'page' | 'meta' = 'config'
 ) {
-  const resolvedOptions =
-    mode === 'config' ? getRouteFromConfig(ctx, route, localeCodes) : getRouteFromMacro(ctx, route, localeCodes)
+  let resolvedOptions
+  if (mode === 'meta') {
+    resolvedOptions = getRouteFromMeta(ctx, route, localeCodes)
+  } else if (mode === 'page') {
+    resolvedOptions = getRouteFromMacro(ctx, route, localeCodes)
+  } else {
+    resolvedOptions = getRouteFromConfig(ctx, route, localeCodes)
+  }
 
   // routing disabled
   if (resolvedOptions === false) {