4.custom-paths.md

title	description
Custom route paths	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 2 ways of configuring custom paths for your pages: Page component or via the Nuxt configuration.

::alert{type="warning"}

Custom paths are not supported when using the no-prefix strategy.

::

Page component

You can use the defineI18nRoute compiler macro to set some custom paths for each page component.

<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.

<script setup>
defineI18nRoute({
  paths: {
    en: '/articles/:name',
    es: '/artículo/:name'
  }
})
</script>

::alert{type="info"}

defineI18nRoute compiler macro is tree-shaked out at build time and is not included in the dist files.

::

Nuxt configuration

Make sure you set the parsePages option to false to disable babel parsing and add your custom paths in the pages option:

export default defineNuxtConfig({
  // ...

  i18n: {
    parsePages: false,   // Disable babel parsing
    pages: {
      about: {
        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
      }
    }
  },

  // ...
})

Note that each key within the pages object should correspond to the relative file path of the route within your pages/ directory excluding the leading /.

Customized route paths must start with a / and not include the locale prefix.

Example 1

Say you have some nested pages like:

pages/
├── [nested]/
├──── [route]/
├────── index.vue
├────── [...slug].vue

Here's how you would configure these particular pages in the configuration:

export default defineNuxtConfig({
  // ...

  i18n: {
    parsePages: false,
    pages: {
      ':nested/:route': {
        en: '/mycustompath/:nested/:route' // Params need to be put back here as you would with vue-router
      },
      ':nested/:route/:slug(.*)*': {
        en: '/mycustompath/:nested/*' // * will match the entire route path after /:nested/
      }
    }
  },

  // ...
})

Example 2

With the following pages directory:

pages/
├── about.vue
├── services/
├──── index.vue
├──── development/
├────── index.vue
├────── app/
├──────── index.vue
├────── website/
├──────── index.vue
├──── coaching/
├────── index.vue

You would need to set up your pages property as follows:

export default defineNuxtConfig({
  // ...

  i18n: {
    parsePages: false,
    pages: {
      about: {
        fr: '/a-propos',
      },
      services: {
        fr: '/offres',
      },
      'services/development': {
        fr: '/offres/developement',
      },
      'services/development/app': {
        fr: '/offres/developement/app',
      },
      'services/development/website': {
        fr: '/offres/developement/site-web',
      },
      'services/coaching': {
        fr: '/offres/formation',
      }
    }
  },

  // ...
})

If a custom path is missing for one of the locales, the defaultLocale custom path is used, if set.