From c103d13e9b5a85057dde42a2d4ff6877858ba43f Mon Sep 17 00:00:00 2001
From: Bobbie Goede <bobbiegoede@gmail.com>
Date: Mon, 30 Sep 2024 13:38:01 +0200
Subject: [PATCH] feat: experimental typed routes (#3142)

---
 build.config.ts                               |   2 +-
 docs/content/docs/5.v9/3.options/10.misc.md   |   3 +
 .../docs/5.v9/4.api/3.compiler-macros.md      |   8 +-
 package.json                                  |   1 +
 playground/nuxt.config.ts                     |   3 +-
 playground/pages/index.vue                    |   3 +-
 pnpm-lock.yaml                                |   3 +
 specs/experimental/typed_pages.spec.ts        |  77 +++++++++++
 .../typed_pages_explicit_disable.spec.ts      |  35 +++++
 src/constants.ts                              |   3 +-
 src/gen.ts                                    |  88 ++++++++++++
 src/module.ts                                 |   2 +-
 src/pages.ts                                  | 126 +++++++++++++++++-
 src/runtime/components/NuxtLinkLocale.ts      |  22 ++-
 src/runtime/composables/index.ts              |  60 +++++++--
 src/runtime/shared-types.ts                   |  17 ++-
 16 files changed, 416 insertions(+), 37 deletions(-)
 create mode 100644 specs/experimental/typed_pages.spec.ts
 create mode 100644 specs/experimental/typed_pages_explicit_disable.spec.ts

diff --git a/build.config.ts b/build.config.ts
index ed764f4b1..68ff1ed23 100644
--- a/build.config.ts
+++ b/build.config.ts
@@ -1,5 +1,5 @@
 import { defineBuildConfig } from 'unbuild'
 
 export default defineBuildConfig({
-  externals: ['node:fs', 'node:url', 'webpack', '@babel/parser']
+  externals: ['node:fs', 'node:url', 'webpack', '@babel/parser', 'unplugin-vue-router', 'unplugin-vue-router/options']
 })
diff --git a/docs/content/docs/5.v9/3.options/10.misc.md b/docs/content/docs/5.v9/3.options/10.misc.md
index ae80b53bb..a5e212780 100644
--- a/docs/content/docs/5.v9/3.options/10.misc.md
+++ b/docs/content/docs/5.v9/3.options/10.misc.md
@@ -18,6 +18,9 @@ About how to define the locale detector, see the [`defineI18nLocaleDetector` API
 - `autoImportTranslationFunctions` (default: `false`) - Automatically imports/initializes `$t`, `$rt`, `$d`, `$n`, `$tm` and `$te` functions in `<script setup>` when used.
 ::callout{icon="i-heroicons-exclamation-triangle" color="amber"}
 This feature relies on [Nuxt's Auto-imports](https://nuxt.com/docs/guide/concepts/auto-imports) and will not work if this has been disabled.
+- `typedPages` (default: `true`) - Generates route types used in composables and configuration, this feature is enabled by default when Nuxt's `experimental.typedRoutes` is enabled.
+::callout{icon="i-heroicons-exclamation-triangle" color="amber"}
+This feature relies on [Nuxt's `experimental.typedRoutes`](https://nuxt.com/docs/guide/going-further/experimental-features#typedpages) and will not work if this is not enabled.
 ::
 
 
diff --git a/docs/content/docs/5.v9/4.api/3.compiler-macros.md b/docs/content/docs/5.v9/4.api/3.compiler-macros.md
index 951c5f74c..26c85f294 100644
--- a/docs/content/docs/5.v9/4.api/3.compiler-macros.md
+++ b/docs/content/docs/5.v9/4.api/3.compiler-macros.md
@@ -25,8 +25,8 @@ defineI18nRoute({
 defineI18nRoute(route: I18nRoute | false) => void
 
 interface I18nRoute {
-  paths?: Record<string, string>
-  locales?: string[]
+  paths?: Record<Locale, `/${string}`>
+  locales?: Locale[]
 }
 ```
 
@@ -42,12 +42,12 @@ An object accepting the following i18n route settings:
 
 - **`paths`**
 
-  - **Type**: `Record<Locale, string>`
+  - **Type**: `Record<Locale, `/${string}`>`
 
     Customize page component routes per locale. You can specify static and dynamic paths for vue-router.
 
 - **`locales`**
 
-  - **Type**: `string[]`
+  - **Type**: `Locale[]`
 
     Some locales to which the page component should be localized.
diff --git a/package.json b/package.json
index 17b9ba757..4151d435c 100644
--- a/package.json
+++ b/package.json
@@ -104,6 +104,7 @@
     "sucrase": "^3.35.0",
     "ufo": "^1.3.1",
     "unplugin": "^1.10.1",
+    "unplugin-vue-router": "^0.10.8",
     "vue-i18n": "^10.0.3",
     "vue-router": "^4.4.5"
   },
diff --git a/playground/nuxt.config.ts b/playground/nuxt.config.ts
index 44b5acce0..b8662d641 100644
--- a/playground/nuxt.config.ts
+++ b/playground/nuxt.config.ts
@@ -121,7 +121,8 @@ export default defineNuxtConfig({
     experimental: {
       localeDetector: './localeDetector.ts',
       switchLocalePathLinkSSR: true,
-      autoImportTranslationFunctions: true
+      autoImportTranslationFunctions: true,
+      typedPages: true
     },
     compilation: {
       // jit: false,
diff --git a/playground/pages/index.vue b/playground/pages/index.vue
index 9e39d5e15..9f5238dba 100644
--- a/playground/pages/index.vue
+++ b/playground/pages/index.vue
@@ -71,7 +71,8 @@ definePageMeta({
     <p>{{ $t('bar.buz', { name: 'buz' }) }}</p>
     <h2>Pages</h2>
     <nav>
-      <NuxtLink :to="localePath('/')">Home</NuxtLink> | <NuxtLink :to="localePath({ name: 'about' })">About</NuxtLink> |
+      <NuxtLink :to="localePath('index')">Home</NuxtLink> |
+      <NuxtLink :to="localePath({ name: 'about' })">About</NuxtLink> |
       <NuxtLink :to="localePath({ name: 'blog' })">Blog</NuxtLink> |
       <NuxtLink :to="localePath({ name: 'server' })">Server</NuxtLink> |
       <NuxtLink :to="localePath({ name: 'category-id', params: { id: 'foo' } })">Category</NuxtLink> |
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 140a67802..412d88d2a 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -72,6 +72,9 @@ importers:
       unplugin:
         specifier: ^1.10.1
         version: 1.10.1
+      unplugin-vue-router:
+        specifier: ^0.10.8
+        version: 0.10.8(rollup@3.29.4)(vue-router@4.4.5(vue@3.5.5(typescript@5.6.2)))(vue@3.5.5(typescript@5.6.2))(webpack-sources@3.2.3)
       vue-i18n:
         specifier: ^10.0.3
         version: 10.0.3(vue@3.5.5(typescript@5.6.2))
diff --git a/specs/experimental/typed_pages.spec.ts b/specs/experimental/typed_pages.spec.ts
new file mode 100644
index 000000000..d9b5bdebd
--- /dev/null
+++ b/specs/experimental/typed_pages.spec.ts
@@ -0,0 +1,77 @@
+import { test, expect, describe } from 'vitest'
+import { fileURLToPath } from 'node:url'
+import { setup } from '../utils'
+import fs from 'node:fs/promises'
+
+await setup({
+  rootDir: fileURLToPath(new URL(`../fixtures/basic_usage`, import.meta.url)),
+  browser: false,
+  // overrides
+  nuxtConfig: {
+    experimental: {
+      typedPages: true
+    }
+  }
+})
+
+describe('`experimental.typedPages` undefined or enabled', async () => {
+  test('generates route types', async () => {
+    expect(
+      await fs.readFile(
+        fileURLToPath(
+          new URL(
+            `../fixtures/basic_usage/.nuxt/___experimental_typed_pages_spec_ts/types/typed-router-i18n.d.ts`,
+            import.meta.url
+          )
+        ),
+        'utf-8'
+      )
+    ).toMatchInlineSnapshot(`
+      "/* eslint-disable */
+      /* prettier-ignore */
+      // @ts-nocheck
+      // Generated by unplugin-vue-router. ‼️ DO NOT MODIFY THIS FILE ‼️
+      // It's recommended to commit this file.
+      // Make sure to add this file to your tsconfig.json file as an "includes" or "files" entry.
+
+      declare module 'vue-router/auto-routes' {
+        import type {
+          RouteRecordInfo,
+          ParamValue,
+          ParamValueOneOrMore,
+          ParamValueZeroOrMore,
+          ParamValueZeroOrOne,
+        } from 'vue-router'
+
+        /**
+         * Route name map generated by unplugin-vue-router
+         */
+        export interface RouteNamedMapI18n {
+          'index': RouteRecordInfo<'index', '/', Record<never, never>, Record<never, never>>,
+          'pathMatch': RouteRecordInfo<'pathMatch', '/:pathMatch(.*)*', { pathMatch?: ParamValueZeroOrMore<true> }, { pathMatch?: ParamValueZeroOrMore<false> }>,
+          'about': RouteRecordInfo<'about', '/about', Record<never, never>, Record<never, never>>,
+          'api-products': RouteRecordInfo<'api-products', '/api/products', Record<never, never>, Record<never, never>>,
+          'api-products-product': RouteRecordInfo<'api-products-product', '/api/products/:product()', { product: ParamValue<true> }, { product: ParamValue<false> }>,
+          'api-products-data': RouteRecordInfo<'api-products-data', '/api/products-data', Record<never, never>, Record<never, never>>,
+          'category-slug': RouteRecordInfo<'category-slug', '/category/:slug()', { slug: ParamValue<true> }, { slug: ParamValue<false> }>,
+          'composables': RouteRecordInfo<'composables', '/composables', Record<never, never>, Record<never, never>>,
+          'experimental-slug': RouteRecordInfo<'experimental-slug', '/experimental/:slug(.*)*', { slug?: ParamValueZeroOrMore<true> }, { slug?: ParamValueZeroOrMore<false> }>,
+          'experimental-auto-import-translation-functions': RouteRecordInfo<'experimental-auto-import-translation-functions', '/experimental/auto-import-translation-functions', Record<never, never>, Record<never, never>>,
+          'greetings': RouteRecordInfo<'greetings', '/greetings', Record<never, never>, Record<never, never>>,
+          'layer-page': RouteRecordInfo<'layer-page', '/layer-page', Record<never, never>, Record<never, never>>,
+          'layer-parent': RouteRecordInfo<'layer-parent', '/layer-parent', Record<never, never>, Record<never, never>>,
+          'layer-parent-layer-child': RouteRecordInfo<'layer-parent-layer-child', '/layer-parent/layer-child', Record<never, never>, Record<never, never>>,
+          'long-text': RouteRecordInfo<'long-text', '/long-text', Record<never, never>, Record<never, never>>,
+          'nested-test-route': RouteRecordInfo<'nested-test-route', '/nested/test-route', Record<never, never>, Record<never, never>>,
+          'nuxt-context-extension': RouteRecordInfo<'nuxt-context-extension', '/nuxt-context-extension', Record<never, never>, Record<never, never>>,
+          'page with spaces': RouteRecordInfo<'page with spaces', '/page%20with%20spaces', Record<never, never>, Record<never, never>>,
+          'post-id': RouteRecordInfo<'post-id', '/post/:id()', { id: ParamValue<true> }, { id: ParamValue<false> }>,
+          'products': RouteRecordInfo<'products', '/products', Record<never, never>, Record<never, never>>,
+          'products-slug': RouteRecordInfo<'products-slug', '/products/:slug()', { slug: ParamValue<true> }, { slug: ParamValue<false> }>,
+          'user-profile': RouteRecordInfo<'user-profile', '/user/profile', Record<never, never>, Record<never, never>>,
+        }
+      }
+      "
+    `)
+  })
+})
diff --git a/specs/experimental/typed_pages_explicit_disable.spec.ts b/specs/experimental/typed_pages_explicit_disable.spec.ts
new file mode 100644
index 000000000..1acf2a622
--- /dev/null
+++ b/specs/experimental/typed_pages_explicit_disable.spec.ts
@@ -0,0 +1,35 @@
+import { test, expect, describe } from 'vitest'
+import { fileURLToPath } from 'node:url'
+import { setup } from '../utils'
+import fs from 'node:fs/promises'
+
+await setup({
+  rootDir: fileURLToPath(new URL(`../fixtures/basic_usage`, import.meta.url)),
+  browser: false,
+  // overrides
+  nuxtConfig: {
+    experimental: {
+      typedPages: true
+    },
+    i18n: {
+      experimental: {
+        typedPages: false
+      }
+    }
+  }
+})
+
+describe('`experimental.typedPages` explicitly disabled', async () => {
+  test('does not generate types', async () => {
+    await expect(
+      fs.access(
+        fileURLToPath(
+          new URL(
+            `../fixtures/basic_usage/.nuxt/___experimental_typed_pages_explicit_disable_spec_ts/types/typed-router-i18n.d.ts`,
+            import.meta.url
+          )
+        )
+      )
+    ).rejects.toThrowError()
+  })
+})
diff --git a/src/constants.ts b/src/constants.ts
index e83815567..c55fbf3a1 100644
--- a/src/constants.ts
+++ b/src/constants.ts
@@ -29,7 +29,8 @@ export const DEFAULT_OPTIONS = {
   experimental: {
     localeDetector: '',
     switchLocalePathLinkSSR: false,
-    autoImportTranslationFunctions: false
+    autoImportTranslationFunctions: false,
+    typedPages: true
   },
   bundle: {
     compositionOnly: true,
diff --git a/src/gen.ts b/src/gen.ts
index 8909cef27..d5202b42a 100644
--- a/src/gen.ts
+++ b/src/gen.ts
@@ -152,6 +152,92 @@ function genImportSpecifier(
   return getLoadPath()
 }
 
+/**
+ * From vuejs/router
+ * https://github.com/vuejs/router/blob/14219b01bee142423265a3aaacd1eac0dcc95071/packages/router/src/typed-routes/route-map.ts
+ * https://github.com/vuejs/router/blob/14219b01bee142423265a3aaacd1eac0dcc95071/packages/router/src/typed-routes/route-location.ts
+ *
+ * Depends on `TypesConfig`
+ * https://github.com/vuejs/router/blob/14219b01bee142423265a3aaacd1eac0dcc95071/packages/router/src/config.ts#L14
+ * Depends on the same mechanism of `RouteNamedMap
+ * https://github.com/vuejs/router/blob/14219b01bee142423265a3aaacd1eac0dcc95071/packages/router/vue-router-auto.d.ts#L4
+ */
+const typedRouterAugmentations = `
+declare module 'vue-router' {
+  import type { RouteNamedMapI18n } from 'vue-router/auto-routes'
+
+  export interface TypesConfig {
+    RouteNamedMapI18n: RouteNamedMapI18n
+  }
+
+  export type RouteMapI18n =
+    TypesConfig extends Record<'RouteNamedMapI18n', infer RouteNamedMap> ? RouteNamedMap : RouteMapGeneric
+    
+  // Prefer named resolution for i18n
+  export type RouteLocationNamedI18n<Name extends keyof RouteMapI18n = keyof RouteMapI18n> =
+      | Name
+      | Omit<RouteLocationAsRelativeI18n, 'path'> & { path?: string }
+      /**
+       * Note: disabled route path string autocompletion, this can break depending on \`strategy\`
+       * this can be enabled again after route resolve has been improved.
+      */
+      // | RouteLocationAsStringI18n
+      // | RouteLocationAsPathI18n
+
+  export type RouteLocationRawI18n<Name extends keyof RouteMapI18n = keyof RouteMapI18n> =
+    RouteMapGeneric extends RouteMapI18n
+      ? RouteLocationAsStringI18n | RouteLocationAsRelativeGeneric | RouteLocationAsPathGeneric
+      :
+          | _LiteralUnion<RouteLocationAsStringTypedList<RouteMapI18n>[Name], string>
+          | RouteLocationAsRelativeTypedList<RouteMapI18n>[Name]
+
+  export type RouteLocationResolvedI18n<Name extends keyof RouteMapI18n = keyof RouteMapI18n> =
+    RouteMapGeneric extends RouteMapI18n
+      ? RouteLocationResolvedGeneric
+      : RouteLocationResolvedTypedList<RouteMapI18n>[Name]
+
+  export interface RouteLocationNormalizedLoadedTypedI18n<
+    RouteMapI18n extends RouteMapGeneric = RouteMapGeneric,
+    Name extends keyof RouteMapI18n = keyof RouteMapI18n
+  > extends RouteLocationNormalizedLoadedGeneric {
+    name: Extract<Name, string | symbol>
+    params: RouteMapI18n[Name]['params']
+  }
+  export type RouteLocationNormalizedLoadedTypedListI18n<RouteMapOriginal extends RouteMapGeneric = RouteMapGeneric> = {
+    [N in keyof RouteMapOriginal]: RouteLocationNormalizedLoadedTypedI18n<RouteMapOriginal, N>
+  }
+  export type RouteLocationNormalizedLoadedI18n<Name extends keyof RouteMapI18n = keyof RouteMapI18n> =
+    RouteMapGeneric extends RouteMapI18n
+      ? RouteLocationNormalizedLoadedGeneric
+      : RouteLocationNormalizedLoadedTypedListI18n<RouteMapI18n>[Name]
+
+  type _LiteralUnion<LiteralType, BaseType extends string = string> = LiteralType | (BaseType & Record<never, never>)
+
+  export type RouteLocationAsStringI18n<Name extends keyof RouteMapI18n = keyof RouteMapI18n> =
+    RouteMapGeneric extends RouteMapI18n
+      ? string
+      : _LiteralUnion<RouteLocationAsStringTypedList<RouteMapI18n>[Name], string>
+
+  export type RouteLocationAsRelativeI18n<Name extends keyof RouteMapI18n = keyof RouteMapI18n> =
+    RouteMapGeneric extends RouteMapI18n
+      ? RouteLocationAsRelativeGeneric
+      : RouteLocationAsRelativeTypedList<RouteMapI18n>[Name]
+
+  export type RouteLocationAsPathI18n<Name extends keyof RouteMapI18n = keyof RouteMapI18n> =
+    RouteMapGeneric extends RouteMapI18n ? RouteLocationAsPathGeneric : RouteLocationAsPathTypedList<RouteMapI18n>[Name]
+
+  /**
+   * Helper to generate a type safe version of the {@link RouteLocationAsRelative} type.
+   */
+  export interface RouteLocationAsRelativeTypedI18n<
+    RouteMapI18n extends RouteMapGeneric = RouteMapGeneric,
+    Name extends keyof RouteMapI18n = keyof RouteMapI18n
+  > extends RouteLocationAsRelativeGeneric {
+    name?: Extract<Name, string | symbol>
+    params?: RouteMapI18n[Name]['paramsRaw']
+  }
+}`
+
 export function generateI18nTypes(nuxt: Nuxt, options: NuxtI18nOptions) {
   const vueI18nTypes = options.types === 'legacy' ? ['VueI18n'] : ['ExportedGlobalComposer', 'Composer']
   const generatedLocales = simplifyLocaleOptions(nuxt, options)
@@ -203,6 +289,8 @@ declare module '#app' {
   }
 }
 
+${typedRouterAugmentations}
+
 ${(options.experimental?.autoImportTranslationFunctions && globalTranslationTypes) || ''}
 
 export {}`
diff --git a/src/module.ts b/src/module.ts
index 5455bd59c..3f84b5330 100644
--- a/src/module.ts
+++ b/src/module.ts
@@ -58,7 +58,7 @@ export default defineNuxtModule<NuxtI18nOptions>({
     /**
      * setup nuxt/pages
      */
-    setupPages(ctx, nuxt)
+    await setupPages(ctx, nuxt)
 
     /**
      * ignore `/` during prerender when using prefixed routing
diff --git a/src/pages.ts b/src/pages.ts
index 0cc11a5d5..d16ff7fc1 100644
--- a/src/pages.ts
+++ b/src/pages.ts
@@ -1,18 +1,22 @@
 import createDebug from 'debug'
-import { extendPages } from '@nuxt/kit'
+import { addTemplate, extendPages } from '@nuxt/kit'
 import { isString } from '@intlify/shared'
 import { parse as parseSFC, compileScript } from '@vue/compiler-sfc'
 import { walk } from 'estree-walker'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import MagicString from 'magic-string'
 import { formatMessage, getRoutePath, parseSegment, readFileSync } from './utils'
 import { localizeRoutes } from './routing'
 import { mergeLayerPages } from './layers'
-import { resolve, parse as parsePath } from 'pathe'
+import { resolve, parse as parsePath, dirname } from 'pathe'
 import { NUXT_I18N_COMPOSABLE_DEFINE_ROUTE } from './constants'
+import { createRoutesContext } from 'unplugin-vue-router'
+import { resolveOptions } from 'unplugin-vue-router/options'
 
 import type { Nuxt, NuxtPage } from '@nuxt/schema'
-import type { NuxtI18nOptions, CustomRoutePages, ComputedRouteOptions, RouteOptionsResolver } from './types'
 import type { Node, ObjectExpression, ArrayExpression } from '@babel/types'
+import type { EditableTreeNode, Options as TypedRouterOptions } from 'unplugin-vue-router'
+import type { NuxtI18nOptions, CustomRoutePages, ComputedRouteOptions, RouteOptionsResolver } from './types'
 import type { I18nNuxtContext } from './context'
 
 const debug = createDebug('@nuxtjs/i18n:pages')
@@ -35,7 +39,7 @@ export type NuxtPageAnalyzeContext = {
   pages: Map<NuxtPage, AnalyzedNuxtPageMeta>
 }
 
-export function setupPages({ localeCodes, options, isSSR }: I18nNuxtContext, nuxt: Nuxt) {
+export async function setupPages({ localeCodes, options, isSSR }: I18nNuxtContext, nuxt: Nuxt) {
   if (!localeCodes.length) return
 
   let includeUnprefixedFallback = !isSSR
@@ -48,7 +52,9 @@ export function setupPages({ localeCodes, options, isSSR }: I18nNuxtContext, nux
   const srcDir = nuxt.options.srcDir
   debug(`pagesDir: ${pagesDir}, srcDir: ${srcDir}, trailingSlash: ${options.trailingSlash}`)
 
-  extendPages(pages => {
+  const typedRouter = await setupExperimentalTypedRoutes(options, nuxt)
+
+  extendPages(async pages => {
     debug('pages making ...', pages)
     const ctx: NuxtPageAnalyzeContext = {
       stack: [],
@@ -61,6 +67,10 @@ export function setupPages({ localeCodes, options, isSSR }: I18nNuxtContext, nux
     const analyzer = (pageDirOverride: string) => analyzeNuxtPages(ctx, pages, pageDirOverride)
     mergeLayerPages(analyzer, nuxt)
 
+    if (typedRouter) {
+      await typedRouter.createContext(pages).scanPages(false)
+    }
+
     const localizedPages = localizeRoutes(pages, {
       ...options,
       includeUnprefixedFallback,
@@ -83,6 +93,112 @@ export function setupPages({ localeCodes, options, isSSR }: I18nNuxtContext, nux
   })
 }
 
+/**
+ * Expression to to find the `RouteNamedMap` generated by uvr, used to replace with `RouteNamedMapI18n`
+ */
+const routeNamedMapTypeRE = /RouteNamedMap\b/
+
+/**
+ * Declaration file containing the generated route types
+ */
+const declarationFile = './types/typed-router-i18n.d.ts'
+
+/**
+ * Setup experiment typed routes feature if enabled
+ */
+async function setupExperimentalTypedRoutes(userOptions: NuxtI18nOptions, nuxt: Nuxt) {
+  if (!nuxt.options.experimental.typedPages || userOptions.experimental?.typedPages === false) {
+    return undefined
+  }
+
+  const dtsFile = resolve(nuxt.options.buildDir, declarationFile)
+
+  /**
+   * Typed route generation from Nuxt with modifications
+   * https://github.com/nuxt/nuxt/blob/781d8c4174c410a7aff6b809817b15eae85d3ba8/packages/nuxt/src/pages/module.ts#L160-L208
+   */
+  function createContext(pages: NuxtPage[]) {
+    const typedRouteroptions: TypedRouterOptions = {
+      routesFolder: [],
+      dts: dtsFile,
+      logs: nuxt.options.debug,
+      watch: false,
+      // eslint-disable-next-line @typescript-eslint/require-await
+      async beforeWriteFiles(rootPage) {
+        rootPage.children.forEach(child => child.delete())
+        function addPage(parent: EditableTreeNode, page: NuxtPage) {
+          // @ts-expect-error TODO: either fix types upstream or figure out another
+          // way to add a route without a file, which must be possible
+          const route = parent.insert(page.path, page.file)
+          if (page.meta) {
+            route.addToMeta(page.meta)
+          }
+          if (page.alias) {
+            route.addAlias(page.alias)
+          }
+          if (page.name) {
+            route.name = page.name
+          }
+          // TODO: implement redirect support
+          // if (page.redirect) {}
+          if (page.children) {
+            page.children.forEach(child => addPage(route, child))
+          }
+        }
+
+        for (const page of pages) {
+          addPage(rootPage, page)
+        }
+      }
+    }
+
+    const context = createRoutesContext(resolveOptions(typedRouteroptions))
+
+    /**
+     * Wrap `scanPages` to rename interface `RouteNamedMap` => `RouteNamedMapI18n`
+     */
+    const originalScanPages = context.scanPages.bind(context)
+    context.scanPages = async function (watchers = false) {
+      await mkdir(dirname(dtsFile), { recursive: true })
+      await originalScanPages(watchers)
+
+      const dtsContent = await readFile(dtsFile, 'utf-8')
+
+      if (routeNamedMapTypeRE.test(dtsContent)) {
+        await writeFile(dtsFile, dtsContent.replace(routeNamedMapTypeRE, 'RouteNamedMapI18n'))
+      }
+    }
+
+    return context
+  }
+
+  addTemplate({
+    filename: resolve(nuxt.options.buildDir, './types/i18n-generated-route-types.d.ts'),
+    getContents: () => {
+      return `// Generated by @nuxtjs/i18n
+declare module 'vue-router' {
+  import type { RouteNamedMapI18n } from 'vue-router/auto-routes'
+
+  export interface TypesConfig {
+    RouteNamedMapI18n: RouteNamedMapI18n
+  }
+}
+
+export {}`
+    }
+  })
+
+  nuxt.hook('prepare:types', ({ references }) => {
+    // This file will be generated by unplugin-vue-router
+    references.push({ path: declarationFile })
+    references.push({ types: './types/i18n-generated-route-types.d.ts' })
+  })
+
+  await createContext(nuxt.apps.default?.pages ?? []).scanPages(false)
+
+  return { createContext }
+}
+
 /**
  * Analyze page path
  */
diff --git a/src/runtime/components/NuxtLinkLocale.ts b/src/runtime/components/NuxtLinkLocale.ts
index e8a1ca6c7..ca386d5c5 100644
--- a/src/runtime/components/NuxtLinkLocale.ts
+++ b/src/runtime/components/NuxtLinkLocale.ts
@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment */
 import { useLocalePath, type Locale } from '#i18n'
 import { defineComponent, computed, h } from 'vue'
 import { defineNuxtLink } from '#imports'
@@ -8,9 +9,14 @@ import type { NuxtLinkProps } from 'nuxt/app'
 
 const NuxtLinkLocale = defineNuxtLink({ componentName: 'NuxtLinkLocale' })
 
-export default defineComponent<NuxtLinkProps & { locale?: Locale }>({
+type NuxtLinkLocaleProps = Omit<NuxtLinkProps, 'to'> & {
+  to?: import('vue-router').RouteLocationNamedI18n
+  locale?: Locale
+}
+
+export default defineComponent<NuxtLinkLocaleProps>({
   name: 'NuxtLinkLocale',
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- FIXME
+
   props: {
     ...NuxtLinkLocale.props,
     locale: {
@@ -23,7 +29,11 @@ export default defineComponent<NuxtLinkProps & { locale?: Locale }>({
     const localePath = useLocalePath()
 
     // From https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/nuxt-link.ts#L57
-    const checkPropConflicts = (props: NuxtLinkProps, main: keyof NuxtLinkProps, sub: keyof NuxtLinkProps): void => {
+    const checkPropConflicts = (
+      props: NuxtLinkLocaleProps,
+      main: keyof NuxtLinkLocaleProps,
+      sub: keyof NuxtLinkProps
+    ): void => {
       if (import.meta.dev && props[main] !== undefined && props[sub] !== undefined) {
         console.warn(`[NuxtLinkLocale] \`${main}\` and \`${sub}\` cannot be used together. \`${sub}\` will be ignored.`)
       }
@@ -31,7 +41,7 @@ export default defineComponent<NuxtLinkProps & { locale?: Locale }>({
 
     const resolvedPath = computed(() => {
       const destination = props.to ?? props.href
-      return destination != null ? localePath(destination, props.locale) : destination
+      return (destination != null ? localePath(destination, props.locale) : destination) as string
     })
 
     // Resolving link type
@@ -52,7 +62,7 @@ export default defineComponent<NuxtLinkProps & { locale?: Locale }>({
         return false
       }
 
-      return destination === '' || destination == null || hasProtocol(destination, { acceptRelative: true })
+      return destination === '' || destination == null || hasProtocol(destination as string, { acceptRelative: true })
     })
 
     /**
@@ -76,7 +86,7 @@ export default defineComponent<NuxtLinkProps & { locale?: Locale }>({
       // @see https://github.com/nuxt-modules/i18n/issues/2498
       delete _props.locale
 
-      return _props
+      return _props as NuxtLinkProps
     }
 
     return () => h(NuxtLinkLocale, getNuxtLinkProps(), slots.default)
diff --git a/src/runtime/composables/index.ts b/src/runtime/composables/index.ts
index 2531df67b..2124fefc0 100644
--- a/src/runtime/composables/index.ts
+++ b/src/runtime/composables/index.ts
@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-unnecessary-type-assertion */
 import { useRequestHeaders, useCookie as useNuxtCookie } from '#imports'
 import { ref, computed, watch, onUnmounted } from 'vue'
 import { parseAcceptLanguage, wrapComposable, runtimeDetectBrowserLanguage } from '../internal'
@@ -24,8 +25,8 @@ import { getLocale, getLocales, getComposer } from '../compatibility'
 
 import type { Ref } from 'vue'
 import type { Locale } from 'vue-i18n'
-import type { RouteLocation, RouteLocationNormalizedLoaded, RouteLocationRaw, Router } from 'vue-router'
-import type { I18nHeadMetaInfo, I18nHeadOptions, SeoAttributesOptions } from '../shared-types'
+import type { I18nHeadMetaInfo, I18nHeadOptions, LocaleObject, SeoAttributesOptions } from '../shared-types'
+import type { RouteLocationAsRelativeI18n, RouteLocationResolvedI18n, RouteMapI18n } from 'vue-router'
 import type { HeadParam } from '../utils'
 
 export * from 'vue-i18n'
@@ -194,7 +195,16 @@ export function useLocaleHead({
  *
  * @public
  */
-export type RouteBaseNameFunction = (givenRoute?: RouteLocationNormalizedLoaded) => string | undefined
+export type RouteBaseNameFunction = <Name extends keyof RouteMapI18n = keyof RouteMapI18n>(
+  route: Name | (Omit<RouteLocationAsRelativeI18n, 'path'> & { path?: string }),
+  /**
+   * Note: disabled route path string autocompletion, this can break depending on `strategy`
+   * this can be enabled again after route resolve has been improved.
+   */
+  // | RouteLocationAsStringI18n
+  // | RouteLocationAsPathI18n
+  locale?: Locale
+) => string
 
 /**
  * The `useRouteBaseName` composable returns a function which returns the route base name.
@@ -207,6 +217,7 @@ export type RouteBaseNameFunction = (givenRoute?: RouteLocationNormalizedLoaded)
  * @public
  */
 export function useRouteBaseName(): RouteBaseNameFunction {
+  // @ts-expect-error - generated types conflict with the generic types we accept
   return wrapComposable(getRouteBaseName)
 }
 
@@ -225,7 +236,17 @@ export function useRouteBaseName(): RouteBaseNameFunction {
  *
  * @public
  */
-export type LocalePathFunction = (route: RouteLocation | RouteLocationRaw, locale?: Locale) => string
+
+export type LocalePathFunction = <Name extends keyof RouteMapI18n = keyof RouteMapI18n>(
+  route: Name | (Omit<RouteLocationAsRelativeI18n, 'path'> & { path?: string }),
+  /**
+   * Note: disabled route path string autocompletion, this can break depending on `strategy`
+   * this can be enabled again after route resolve has been improved.
+   */
+  // | RouteLocationAsStringI18n
+  // | RouteLocationAsPathI18n
+  locale?: Locale
+) => string
 
 /**
  * The `useLocalePath` composable returns function  that resolve the locale path.
@@ -238,6 +259,7 @@ export type LocalePathFunction = (route: RouteLocation | RouteLocationRaw, local
  * @public
  */
 export function useLocalePath(): LocalePathFunction {
+  // @ts-expect-error - generated types conflict with the generic types we accept
   return wrapComposable(localePath)
 }
 
@@ -256,11 +278,16 @@ export function useLocalePath(): LocalePathFunction {
  *
  * @public
  */
-export type LocaleRouteFunction = (
-  route: RouteLocationRaw,
+export type LocaleRouteFunction = <Name extends keyof RouteMapI18n = keyof RouteMapI18n>(
+  route: Name | (Omit<RouteLocationAsRelativeI18n, 'path'> & { path?: string }),
+  /**
+   * Note: disabled route path string autocompletion, this can break depending on `strategy`
+   * this can be enabled again after route resolve has been improved.
+   */
+  // | RouteLocationAsStringI18n
+  // | RouteLocationAsPathI18n
   locale?: Locale
-) => ReturnType<Router['resolve']> | undefined
-
+) => RouteLocationResolvedI18n<Name> | undefined
 /**
  * The `useLocaleRoute` composable returns function that resolve the locale route.
  *
@@ -272,6 +299,7 @@ export type LocaleRouteFunction = (
  * @public
  */
 export function useLocaleRoute(): LocaleRouteFunction {
+  // @ts-expect-error - generated types conflict with the generic types we accept
   return wrapComposable(localeRoute)
 }
 
@@ -290,7 +318,16 @@ export function useLocaleRoute(): LocaleRouteFunction {
  *
  * @public
  */
-export type LocaleLocationFunction = (route: RouteLocationRaw, locale?: Locale) => Location | RouteLocation | undefined
+export type LocaleLocationFunction = <Name extends keyof RouteMapI18n = keyof RouteMapI18n>(
+  route: Name | (Omit<RouteLocationAsRelativeI18n, 'path'> & { path?: string }),
+  /**
+   * Note: disabled route path string autocompletion, this can break depending on `strategy`
+   * this can be enabled again after route resolve has been improved.
+   */
+  // | RouteLocationAsStringI18n
+  // | RouteLocationAsPathI18n
+  locale?: Locale
+) => RouteLocationResolvedI18n<Name> | undefined
 
 /**
  * The `useLocaleLocation` composable returns function that resolve the locale location.
@@ -303,6 +340,7 @@ export type LocaleLocationFunction = (route: RouteLocationRaw, locale?: Locale)
  * @public
  */
 export function useLocaleLocation(): LocaleLocationFunction {
+  // @ts-expect-error - generated types conflict with the generic types we accept
   return wrapComposable(localeLocation)
 }
 
@@ -351,7 +389,7 @@ export function useBrowserLocale(): string | null {
   const headers = useRequestHeaders(['accept-language'])
   return (
     findBrowserLocale(
-      normalizedLocales,
+      normalizedLocales as LocaleObject[],
       import.meta.client ? (navigator.languages as string[]) : parseAcceptLanguage(headers['accept-language'] || '')
     ) || null
   )
@@ -417,7 +455,7 @@ export interface I18nRoute {
    *
    * @description You can specify static and dynamic paths for vue-router.
    */
-  paths?: Partial<Record<Locale, string>>
+  paths?: Partial<Record<Locale, `/${string}`>>
   /**
    * Some locales to which the page component should be localized.
    */
diff --git a/src/runtime/shared-types.ts b/src/runtime/shared-types.ts
index 27fd64cc5..475d4703b 100644
--- a/src/runtime/shared-types.ts
+++ b/src/runtime/shared-types.ts
@@ -2,6 +2,7 @@ import type { Locale, I18nOptions } from 'vue-i18n'
 import type { ParsedPath } from 'path'
 import type { PluginOptions } from '@intlify/unplugin-vue-i18n'
 import type { NuxtPage } from '@nuxt/schema'
+import type { RouteMapGeneric, RouteMapI18n } from 'vue-router'
 
 // Options
 export const STRATEGY_PREFIX = 'prefix'
@@ -77,13 +78,10 @@ export interface RootRedirectOptions {
   statusCode: number
 }
 
-export type CustomRoutePages = {
-  [key: string]:
-    | false
-    | {
-        [key: string]: false | string
-      }
+type RouteLocationAsStringTypedListI18n<T = RouteMapGeneric extends RouteMapI18n ? RouteMapGeneric : RouteMapI18n> = {
+  [N in keyof T]?: Partial<Record<Locale, `/${string}` | false>> | false
 }
+export type CustomRoutePages = RouteLocationAsStringTypedListI18n
 
 export interface ExperimentalFeatures {
   localeDetector?: string
@@ -94,6 +92,13 @@ export interface ExperimentalFeatures {
    * @defaultValue `false`
    */
   autoImportTranslationFunctions?: boolean
+
+  /**
+   * Generates types for i18n routing helper
+   *
+   * @defaultValue `true`
+   */
+  typedPages?: boolean
 }
 
 export interface BundleOptions