feat: custome route path for component with defineI18nRoute (nuxt-m…

…odules#1544)

.eslintignore

@@ -1,5 +1,6 @@
 dist
 playground
 specs/fixtures
+test/fixtures
 coverage
 docs/components/content/Logo.vue

TODO.md

@@ -14,8 +14,8 @@ This todo is based on [nuxt/i18n](https://i18n.nuxtjs.org/) docs.
   - [x] prefix
   - [x] prefix_and_default
   - [x] Configurations
-- [ ] Custom route paths
-  - [ ] In-component options
+- [x] Custom route paths
+  - [x] In-component options
   - [x] Module's configuration
 - [ ] Ignoring localized routes
   - [ ] Pick localized routes
@@ -83,6 +83,10 @@ This todo is based on [nuxt/i18n](https://i18n.nuxtjs.org/) docs.
 - [x] useLocaleHead (same `$nuxtI18nHead` )
 - [x] useBrowserLocale (same `getBrowserLocale`)
 
+### Compiler Macros (NWE!)
+
+- [x] defineI18nRoute (same `nuxtI18n` component options)
+
 ### Extension of Vuex
 
 - [ ] $i18n

build.config.ts

@@ -1,5 +1,5 @@
 import { defineBuildConfig } from 'unbuild'
 
 export default defineBuildConfig({
-  externals: ['node:fs', '@intlify/vue-i18n-bridge', 'webpack']
+  externals: ['node:fs', 'node:url', '@intlify/vue-i18n-bridge', 'webpack']
 })

docs/content/30.guide/4.custom-paths.md

@@ -3,31 +3,49 @@ title: Custom route paths
 description: 'Customize the names of the paths for specific locale.'
 ---
 
-::alert{type="warning"}
-// TODO:
-🚧 This feature is not implemented **fully** yet.
-::
-
-In some cases, you might want to translate URLs in addition to having them prefixed with the locale code. There are 2 ways of configuring custom paths for your pages: [in-component options](#in-component-options) or via the [module's configuration](#modules-configuration).
+In some cases, you might want to translate URLs in addition to having them prefixed with the locale code. There are 2 ways of configuring custom paths for your pages: [Compiler macro](#compiler-macro) or via the [Nuxt configuration](#nuxt-configuration).
 
 ::alert{type="warning"}
 Custom paths are not supported when using the `no-prefix` [strategy](/strategies).
 ::
 
-### In-component options
+### Compiler macro
 
-::alert{type="warning"}
-// TODO:
-🚧 This feature is not implemented yet.
+You can use the `defineI18nRoute` compiler macro to set some custom paths for each page component.
+
+```html {}[pages/about.vue]
+<script setup>
+defineI18nRoute({
+  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 put the params in the URI similarly to how you would do it in vue-router.
+
+```html {}[pages/articles/[name].vue]
+<script setup>
+defineI18nRoute({
+  paths: {
+    en: '/articles/:name',
+    es: '/artículo/:name'
+  }
+})
+```
+
+::alert{type="info"}
+`defineI18nRoute` compiler macro is tree-shaked out at build time and is not included in the dist files.
 ::
 
-### Module's configuration
+### Nuxt configuration
 
 Make sure you set the `parsePages` option to `false` to disable babel parsing and add your custom paths in the `pages` option:
 
 ```js {}[nuxt.config.js]
-import { defineNuxtConfig } from 'nuxt'
-
 export default defineNuxtConfig({
   // ...
 
@@ -65,8 +83,6 @@ pages/
 Here's how you would configure these particular pages in the configuration:
 
 ```js {}[nuxt.config.js]
-import { defineNuxtConfig } from 'nuxt'
-
 export default defineNuxtConfig({
   // ...
 
@@ -108,8 +124,6 @@ pages/
 You would need to set up your `pages` property as follows:
 
 ```js {}[nuxt.config.js]
-import { defineNuxtConfig } from 'nuxt'
-
 export default defineNuxtConfig({
   // ...
 

docs/content/50.API/2.compiler-macros.md

@@ -0,0 +1,44 @@
+---
+title: Compiler Macros
+description: 'Compiler Macros for `@nuxtjs/i18n`'
+---
+
+## `defineI18nRoute`
+
+`defineI18nRoute` is a compiler macro that you can use to set custom route paths for your **page** components located in the `pages/` directory (unless [set otherwise](https://v3.nuxtjs.org/api/configuration/nuxt.config#pages)). This way you can set custom route paths for each static or dynamic route of your Nuxt application.
+
+```vue [pages/some-page.vue]
+<script setup>
+defineI18nRoute({
+  paths: {
+    en: '/about-us',
+    fr: '/a-propos',
+    ja: '/about-ja'
+  }
+})
+</script>
+```
+
+## Type
+
+```ts
+defineI18nRoute(route: I18nRoute) => void
+
+interface I18nRoute {
+  paths?: Record<Locale, string>
+}
+```
+
+## Parameters
+
+### `paths`
+
+- **Type**: `I18nRoute`
+
+  An object accepting the following i18n route settings:
+
+  **`paths`**
+
+  - **Type**: `Record<Locale, string>`
+
+    Customize page component routes per locale. You can specify static and dynamic paths for vue-router.

package.json

@@ -76,9 +76,11 @@
     "is-https": "^4.0.0",
     "js-cookie": "^3.0.1",
     "knitwork": "^0.1.2",
+    "magic-string": "^0.26.5",
     "mlly": "^0.5.4",
     "pathe": "^0.3.2",
     "ufo": "^0.8.5",
+    "unplugin": "^0.9.6",
     "vue-i18n": "^9.3.0-beta.6",
     "vue-i18n-routing": "^0.6.0"
   },

playground/nuxt.config.ts

@@ -45,20 +45,21 @@ export default defineNuxtConfig({
     // strategy: 'no_prefix',
     // strategy: 'prefix',
     // strategy: 'prefix_and_default',
+    parsePages: true,
     pages: {
       about: {
         ja: '/about-ja'
       }
     },
-    differentDomains: true,
-    // detectBrowserLanguage: false,
-    detectBrowserLanguage: {
-      // alwaysRedirect: true,
-      useCookie: false
-      // cookieKey: 'i18n_redirected',
-      // cookieKey: 'my_custom_cookie_name',
-      // redirectOn: 'root'
-    },
+    // differentDomains: true,
+    detectBrowserLanguage: false,
+    // detectBrowserLanguage: {
+    //   // alwaysRedirect: true,
+    //   useCookie: false
+    //   // cookieKey: 'i18n_redirected',
+    //   // cookieKey: 'my_custom_cookie_name',
+    //   // redirectOn: 'root'
+    // },
     onBeforeLanguageSwitch: (oldLocale, newLocale, initial, context) => {
       console.log('onBeforeLanguageSwitch', oldLocale, newLocale, initial)
     },

playground/pages/about/index.vue

@@ -23,17 +23,21 @@ export default defineComponent({
     useHead({
       meta: [{ property: 'og:title', content: 'this is og title' }]
     })
+    defineI18nRoute({
+      paths: {
+        en: '/about-us',
+        fr: '/a-propos',
+        ja: '/about-ja'
+      }
+    })
+    definePageMeta({
+      title: 'pages.title.about'
+    })
     return {}
   }
 })
 </script>
 
-<script setup lang="ts">
-definePageMeta({
-  title: 'pages.title.about'
-})
-</script>
-
 <template>
   <div>
     <nav>

playground/pages/blog.vue

@@ -0,0 +1,15 @@
+<template>
+  <div>
+    <h1>This is blog page</h1>
+  </div>
+</template>
+
+<script setup>
+defineI18nRoute({
+  paths: {
+    en: '/blog-us',
+    fr: '/a-blog',
+    ja: '/blog-ja'
+  }
+})
+</script>

playground/pages/index.vue

@@ -31,8 +31,8 @@ const availableLocales = computed(() => {
     <h2>{{ $t('hello', { name: 'nuxt3' }) }}</h2>
     <h2>Pages</h2>
     <nav>
-      <NuxtLink :to="localePath('/')">Home</NuxtLink> |
-      <NuxtLink :to="localePath('/about')">About</NuxtLink>
+      <NuxtLink :to="localePath('/')">Home</NuxtLink> | <NuxtLink :to="localePath({ name: 'about' })">About</NuxtLink> |
+      <NuxtLink :to="localePath({ name: 'blog' })">Blog</NuxtLink>
     </nav>
     <h2>Current Language: {{ getLocaleName(locale) }}</h2>
     <h2>Current Strategy: {{ strategy }}</h2>

specs/custom_route_paths/compiler_macro.spec.ts

@@ -0,0 +1,53 @@
+import { test, expect } from 'vitest'
+import { fileURLToPath } from 'node:url'
+import { setup, url, createPage } from '@nuxt/test-utils'
+
+await setup({
+  rootDir: fileURLToPath(new URL(`../fixtures/head`, import.meta.url)),
+  browser: true,
+  // overrides
+  nuxtConfig: {
+    i18n: {
+      defaultLocale: 'en',
+      parsePages: true
+    }
+  }
+})
+
+test('can access to custom route path', async () => {
+  const home = url('/')
+  const page = await createPage()
+  await page.goto(home)
+
+  await page.locator('#link-blog').click()
+  await page.waitForTimeout(1000)
+
+  expect(await page.url()).include('/blog-us')
+
+  await page.goBack()
+  await page.locator('#lang-switcher-with-nuxt-link a').click()
+
+  await page.locator('#link-blog').click()
+  await page.waitForTimeout(1000)
+
+  expect(await page.url()).include('/fr/a-blog')
+})
+
+test('can access to custom dynamic route path', async () => {
+  const home = url('/')
+  const page = await createPage()
+  await page.goto(home)
+
+  await page.locator('#link-category').click()
+  await page.waitForTimeout(1000)
+
+  expect(await page.url()).include('/categories/foo')
+
+  await page.goBack()
+  await page.locator('#lang-switcher-with-nuxt-link a').click()
+
+  await page.locator('#link-category').click()
+  await page.waitForTimeout(1000)
+
+  expect(await page.url()).include(encodeURI('/fr/catégories/foo'))
+})

specs/custom_route_paths.spec.ts/module_configration.spec.ts → specs/custom_route_paths/module_configration.spec.ts

@@ -10,6 +10,7 @@ await setup({
   nuxtConfig: {
     i18n: {
       defaultLocale: 'en',
+      parsePages: false,
       pages: {
         about: {
           fr: '/about-fr'

specs/fixtures/head/locales/en-US.json

@@ -1,5 +1,6 @@
 {
   "home": "Homepage",
   "about": "About us",
-  "posts": "Posts"
+  "posts": "Posts",
+  "categories": "Categories"
 }

specs/fixtures/head/locales/fr-FR.json

@@ -1,5 +1,6 @@
 {
   "home": "Accueil",
   "about": "À propos",
-  "posts": "Articles"
+  "posts": "Articles",
+  "categories": "Catégories"
 }

specs/fixtures/head/pages/blog.vue

@@ -0,0 +1,14 @@
+<template>
+  <div>
+    <h1>This is blog page</h1>
+  </div>
+</template>
+
+<script setup>
+defineI18nRoute({
+  paths: {
+    en: '/blog-us',
+    fr: '/a-blog'
+  }
+})
+</script>

specs/fixtures/head/pages/categories.vue

@@ -0,0 +1,14 @@
+<template>
+  <div>
+    <NuxtPage />
+  </div>
+</template>
+
+<script setup>
+defineI18nRoute({
+  paths: {
+    en: '/categories/:id',
+    fr: '/catégories/:id'
+  }
+})
+</script>

specs/fixtures/head/pages/categories/[id].vue

@@ -0,0 +1,5 @@
+<template>
+  <div>
+    <h1>This is category page</h1>
+  </div>
+</template>

specs/fixtures/head/pages/index.vue

@@ -34,5 +34,9 @@ definePageMeta({
       <code id="home-use-async-data">{{ data }}</code>
     </section>
     <NuxtLink id="link-about" exact :to="localePath('about')">{{ $t('about') }}</NuxtLink>
+    <NuxtLink id="link-blog" :to="localePath({ name: 'blog' })">{{ $t('posts') }}</NuxtLink>
+    <NuxtLink id="link-category" :to="localePath({ name: 'categories', params: { id: 'foo' } })">{{
+      $t('categories')
+    }}</NuxtLink>
   </div>
 </template>