Skip to content

Commit

Permalink
docs: move dynamic route parameters section
Browse files Browse the repository at this point in the history
  • Loading branch information
@BobbieGoede
BobbieGoede committed Oct 9, 2024
1 parent 94abef4 commit 021ff73
Show file tree
Hide file tree
Showing 2 changed files with 93 additions and 89 deletions.
121 changes: 93 additions & 28 deletions docs/content/docs/5.v9/2.guide/3.custom-paths.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Which method is used is configured by setting the [`customRoutes` options](/docs
Custom paths are not supported when using the `no_prefix` [strategy](/docs/guide) unless combined with [`differentDomains`](/docs/guide/different-domains).
::

### Module configuration
## Module configuration

Make sure you set the `customRoutes` option to `config` and add your custom paths in the `pages` option:

Expand Down Expand Up @@ -65,17 +65,18 @@ const localePath = useLocalePath()
Specifying a path to `localePath` is not supported, currently.
::

#### Example 1: Basic URL localization
### Example 1: Basic URL localization

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

```
pages/
├── about.vue
├── me.vue
├── services/
├──── index.vue
├──── advanced.vue

```bash [Directory structure]
| pages/
| about.vue
| me.vue
| services/
| index.vue
| advanced.vue
```

You would need to set up your `pages` property as follows:
Expand Down Expand Up @@ -109,20 +110,21 @@ If the view is in a sub-directory you should use folder name and vue files name
All URLs must start with `/`
::

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

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

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

```bash [Directory structure]
| pages/
| about.vue
| services/
| coaching.vue
| index.vue
| development/
| app.vue
| website.vue
| index.vue
```

You would need to set up your `pages` property as follows:
Expand Down Expand Up @@ -157,17 +159,19 @@ export default defineNuxtConfig({

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

#### Example 3: Dynamic Routes
### Example 3: Dynamic Routes

Say you have some dynamic routes like:

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

```bash [Directory structure]
| pages/
| blog/
| [date]/
| [slug].vue
```


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

```ts [nuxt.config.ts]
Expand All @@ -186,7 +190,7 @@ export default defineNuxtConfig({
})
```

### Page component
## Page component

::callout{icon="i-heroicons-exclamation-triangle" color="amber" title="notice"}
Note for those updating to `v8.0.1` or higher
Expand Down Expand Up @@ -226,7 +230,68 @@ To configure a custom path for a dynamic route, you need to use it in double squ
::


### `definePageMeta({ name: '...' })` caveat
## Dynamic route parameters

Dealing with dynamic route parameters requires a bit more work because you need to provide parameters translations to **Nuxt i18n module**. The composable `useSetI18nParams` can be used to set translations for route parameters, this is used to set SEO tags as well as changing the routes returned by `switchLocalePath`.

::callout{icon="i-heroicons-exclamation-triangle" color="amber"}
During SSR it matters when and where you set i18n parameters, since there is no reactivity during SSR.

:br :br
Components which have already been rendered do not update by changes introduced by pages and components further down the tree. Instead, these links are updated on the client side during hydration, in most cases this should not cause issues.

:br :br
This is not the case for SEO tags, these are updated correctly during SSR regardless of when and where i18n parameters are set.

:br :br
Check out the experimental [`switchLocalePathLinkSSR`](/docs/options/misc#experimental) feature, which combined with the [`<SwitchLocalePathLink>`](/docs/api/components#switchlocalepathlink) component, correctly renders links during SSR regardless of where and when it is used.
::

An example (replace `slug` with the applicable route parameter):

```vue
<script setup>
// fetch product from API... (red mug)
const setI18nParams = useSetI18nParams()
setI18nParams({
en: { slug: data.slugs.en }, // slug: 'red-mug'
nl: { slug: data.slugs.nl } // slug: 'rode-mok'
})
const switchLocalePath = useSwitchLocalePath()
switchLocalePath('en') // /products/red-mug
switchLocalePath('nl') // /nl/products/rode-mok
</script>
<template>
<!-- pages/products/[slug].vue -->
</template>
```

Note that for the special case of a catch-all route named like `[...pathMatch.vue]`, the key of the object needs to say `pathMatch`. For example:

```vue
<script>
const setI18nParams = useSetI18nParams()
setI18nParams({
en: { pathMatch: ['not-found-my-post'] },
fr: { pathMatch: ['not-found-mon-article'] }
})
</script>
<template>
<!-- pages/[...pathMatch].vue -->
</template>
```

Note that a catch all route is defined **as an array**. In this case, there is only one element, but if you want to use a sub-path, for example `/not-found/post`, define multiple elements as in `['not-found', 'post']`. You will need to define more than one, e.g. `['not-found', 'post']`.

::callout{icon="i-heroicons-light-bulb"}
**Nuxt i18n module** won't reset parameters translations for you, this means that if you use identical parameters for different routes, navigating between those routes might result in conflicting parameters. Make sure you always set params translations in such cases.
::

## `definePageMeta({ name: '...' })` caveat

By default Nuxt overwrites generated route values at build time which breaks custom named routes (setting `name` with `definePageMeta`) when resolving localized paths.

Expand Down
61 changes: 0 additions & 61 deletions docs/content/docs/5.v9/2.guide/8.lang-switcher.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -69,67 +69,6 @@ const availableLocales = computed(() => {
</template>
```

## Dynamic route parameters

Dealing with dynamic route parameters requires a bit more work because you need to provide parameters translations to **Nuxt i18n module**. The composable `useSetI18nParams` can be used to set translations for route parameters, this is used to set SEO tags as well as changing the routes returned by `switchLocalePath`.

::callout{icon="i-heroicons-exclamation-triangle" color="amber"}
During SSR it matters when and where you set i18n parameters, since there is no reactivity during SSR.

:br :br
Components which have already been rendered do not update by changes introduced by pages and components further down the tree. Instead, these links are updated on the client side during hydration, in most cases this should not cause issues.

:br :br
This is not the case for SEO tags, these are updated correctly during SSR regardless of when and where i18n parameters are set.

:br :br
Check out the experimental [`switchLocalePathLinkSSR`](/docs/options/misc#experimental) feature, which combined with the [`<SwitchLocalePathLink>`](/docs/api/components#switchlocalepathlink) component, correctly renders links during SSR regardless of where and when it is used.
::

An example (replace `slug` with the applicable route parameter):

```vue
<script setup>
// fetch product from API... (red mug)
const setI18nParams = useSetI18nParams()
setI18nParams({
en: { slug: data.slugs.en }, // slug: 'red-mug'
nl: { slug: data.slugs.nl } // slug: 'rode-mok'
})
const switchLocalePath = useSwitchLocalePath()
switchLocalePath('en') // /products/red-mug
switchLocalePath('nl') // /nl/products/rode-mok
</script>
<template>
<!-- pages/products/[slug].vue -->
</template>
```

Note that for the special case of a catch-all route named like `[...pathMatch.vue]`, the key of the object needs to say `pathMatch`. For example:

```vue
<script>
const setI18nParams = useSetI18nParams()
setI18nParams({
en: { pathMatch: ['not-found-my-post'] },
fr: { pathMatch: ['not-found-mon-article'] }
})
</script>
<template>
<!-- pages/[...pathMatch].vue -->
</template>
```

Note that a catch all route is defined **as an array**. In this case, there is only one element, but if you want to use a sub-path, for example `/not-found/post`, define multiple elements as in `['not-found', 'post']`. You will need to define more than one, e.g. `['not-found', 'post']`.

::callout{icon="i-heroicons-light-bulb"}
**Nuxt i18n module** won't reset parameters translations for you, this means that if you use identical parameters for different routes, navigating between those routes might result in conflicting parameters. Make sure you always set params translations in such cases.
::

## Wait for page transition

By default, the locale will be changed right away when navigating to a route with a different locale which means that if you have a page transition, it will fade out the page with the text already switched to the new language and fade back in with the same content.
Expand Down

0 comments on commit 021ff73

Please sign in to comment.