Skip to content

Commit

Permalink
feat!: custom routes optimized for Nuxt 3 file based routing (#1673)
Browse files Browse the repository at this point in the history 
* feat!: custom routes optimized for Nuxt 3 file based routing

* finish implementation

* fix: update custom routes & ignoring for page components

* replace to customRoutes option
  • Loading branch information
@kazupon
kazupon committed Nov 26, 2022
1 parent ccef92b commit a7fc4de
Show file tree
Hide file tree
Showing 30 changed files with 1,386 additions and 727 deletions.
75 changes: 75 additions & 0 deletions docs/content/2.guide/14.migrating.md
View file
Expand Up @@ -7,6 +7,62 @@ Follow this guide to upgrade from one major version to the other.

## Upgrading from `nuxtjs/i18n` v7.x

### Change the route key rules in `pages` option

The key of route set in the `pages` option has been changed to be file-based relative to the `pages/` directory in Nuxt, and **excluding the leading `/`**.

The reason is that it is more intuitive to match Nuxt file-based routing.


Nuxt2:

```asciidoc
pages/
├── about.vue
├── users/
├──── _id/
├────── profile.vue
├── index.vue
```
```js {}[nuxt.config.js]
i18n: {
parsePages: false,
pages: {
about: {
fr: '/a-propos',
},
'users/_id/profile': {
fr: '/u/:id/profil',
}
}
}
```
Nuxt3:
```asciidoc
pages/
├── about.vue
├── users/
├──── [id]/
├────── profile.vue
├── index.vue
```
```ts {}[nuxt.config.ts]
i18n: {
customRoutes: 'config',
pages: {
about: {
fr: '/a-propos',
},
'users/[id]/profile': {
fr: '/u/[id]/profil',
}
}
}
```
### Deprecated `localeLocation()`
Expand Down Expand Up @@ -50,6 +106,25 @@ defineI18nRoute({
</script>
```
### Deprecated `parsePages` option
Use `customRoutes` option. because the option name `parsePages` is not intuitive.
```diff {}[nuxt.config.ts]
export default defineNuxtConfig({
modules: [
'@nuxtjs/i18n'
],
i18n: {
// ...
- parsePages: false,
+ customRoutes: 'config',
// ...
}
})
```
### Deprecated `vuex` option
Use `dynamicRouteParams` option. because, vuex no longer requires in Nuxt3.
Expand Down
170 changes: 86 additions & 84 deletions docs/content/2.guide/4.custom-paths.md
View file
Expand Up @@ -3,59 +3,30 @@ 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 2 ways of configuring custom paths for your pages: [Page component](#page-component) or via the [Nuxt configuration](#nuxt-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 [Module configuration](#nodule-configuration) or your pages [Page component](#page-component).

::alert{type="warning"}

Custom paths are not supported when using the `no-prefix` [strategy](/guide/routing-strategies).

::

### Page component

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

```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>
```
Make sure you set the `customRoutes` option to `config` and add your custom paths in the `pages` option:

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'
}
})
</script>
```

::alert{type="info"}
::alert{type="warning"}

`defineI18nRoute` compiler macro is tree-shaked out at build time and is not included in the dist files.
`parsePages` option will be deprecated in the v8 official release.

::

### 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]
```ts {}[nuxt.config.ts]
export default defineNuxtConfig({
// ...

i18n: {
parsePages: false, // Disable babel parsing
customRoutes: 'config', // disable custom route with page components
pages: {
about: {
en: '/about-us', // -> accessible at /about-us (no prefix since it's the default locale)
Expand All @@ -69,79 +40,42 @@ export default defineNuxtConfig({
})
```

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:

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

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

```js {}[nuxt.config.js]
export default defineNuxtConfig({
// ...
Note that each key within the `pages` object should **correspond to the relative file-based path (excluding `.vue` file extension) of the route within your `pages/` directory excluding the leading `/`**.

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/
}
}
},

// ...
})
```
Customized route paths **must start with a `/`** and **not include the locale prefix**.

#### Example 2
#### Example 1: Localize the part of URL

With the following `pages` directory:
You have some routes with the following `pages` directory:

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

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

```js {}[nuxt.config.js]
```ts {}[nuxt.config.ts]
export default defineNuxtConfig({
// ...

i18n: {
parsePages: false,
customRoutes: 'config',
pages: {
about: {
fr: '/a-propos',
},
services: {
'services/index': {
fr: '/offres',
},
'services/development': {
'services/development/index': {
fr: '/offres/developement',
},
'services/development/app': {
Expand All @@ -161,3 +95,71 @@ export default defineNuxtConfig({
```

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

#### Example 2: Dynamic Routes

Say you have some dynamic routes like:

```asciidoc
pages/
├── blog/
├──── [date]/
├────── [slug].vue
```

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

```ts {}[nuxt.config.ts]
export default defineNuxtConfig({
// ...

i18n: {
customRoutes: 'config',
pages: {
'blog/[date]/[slug]': {
// params need to be put back here as you would with Nuxt Dynamic Routes
// https://nuxt.com/docs/guide/directory-structure/pages#dynamic-routes
ja: '/blog/tech/[date]/[slug]'
// ...
},
}
},

// ...
})
```

### Page component

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 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):

```html {}[pages/articles/[name].vue]
<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.

::
14 changes: 7 additions & 7 deletions docs/content/2.guide/5.ignoring-localized-routes.md
View file
Expand Up @@ -9,12 +9,12 @@ This feature is not supported with the `no-prefix` [strategy](/guide/routing-str

::

If you'd like some pages to be available in some languages only, you can configure the list of supported languages to override the global settings. The options can be specified within either the page components themselves or globaly, within then module options.
If you'd like some pages to be available in some languages only, you can configure the list of supported languages to override the global settings. The options can be specified within either the page components themselves or globaly, within then module configration.

### Pick localized routes

::code-group
::code-block{label="Page component" active}
::code-block{label="Page components" active}
```js {}[pages/about.vue]
<script setup>
defineI18nRoute({
Expand All @@ -23,10 +23,10 @@ If you'd like some pages to be available in some languages only, you can configu
</script>
```
::
::code-block{label="Nuxt configuration"}
::code-block{label="Module configuration"}
```js {}[nuxt.config.js]
i18n: {
parsePages: false,
customRoutes: false,
pages: {
about: {
en: false,
Expand All @@ -40,17 +40,17 @@ If you'd like some pages to be available in some languages only, you can configu
### Disable localized routes

::code-group
::code-block{label="Page component" active}
::code-block{label="Page components" active}
```js {}[pages/about.vue]
<script setup>
defineI18nRoute(false)
</script>
```
::
::code-block{label="Nuxt configuration"}
::code-block{label="Module configuration"}
```js {}[nuxt.config.js]
i18n: {
parsePages: false,
customRoutes: 'config',
pages: {
about: false
}
Expand Down
15 changes: 14 additions & 1 deletion docs/content/3.options/2.routing.md
View file
Expand Up @@ -91,12 +91,25 @@ Routes generation strategy. Can be set to one of the following:

Whether [custom paths](/guide/custom-paths) are extracted from page files

::alert{type="warning"}

`parsePages` option will be deprecated in the v8 official release.

::

## `customRoutes`

- type: `string` (`page` or `config`) | `undefined`
- default: `page`

Whether [custom paths](/guide/custom-paths) are extracted from page files

## `pages`

- type: `object`
- default: `{}`

If `parsePages` option is disabled, the module will look for custom routes in the `pages` option. Refer to the [Routing](/guide/routing-strategies) for usage.
If `customRoutes` option is disabled with `config`, the module will look for custom routes in the `pages` option. Refer to the [Routing](/guide/routing-strategies) for usage.

## `onBeforeLanguageSwitch`

Expand Down

0 comments on commit a7fc4de

Please sign in to comment.