docs: move dynamic parameters section (#3170)

nuxt-modules · Oct 9, 2024 · c56a599 · c56a599
1 parent ea9b40e
commit c56a599
Show file tree

Hide file tree

Showing 2 changed files with 73 additions and 70 deletions.
diff --git a/docs/content/docs/5.v9/2.guide/3.custom-paths.md b/docs/content/docs/5.v9/2.guide/3.custom-paths.md
@@ -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:
 
@@ -65,11 +65,12 @@ const localePath = useLocalePath()
 Passing a path to `localePath` is currently not supported.
 ::
 
-#### Example 1: Basic URL localization
+### Example 1: Basic URL localization
 
 You have some routes with the following `pages` directory:
 
-```bash
+
+```bash [Directory structure]
 -| pages/
 ---| me.vue
 ---| about.vue
@@ -106,11 +107,12 @@ export default defineNuxtConfig({
 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:
 
-```bash
+
+```bash [Directory structure]
 -| pages/
 ---| about.vue
 ---| services/
@@ -154,11 +156,12 @@ 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:
 
-```bash
+
+```bash [Directory structure]
 -| pages/
 ---| blog/
 -----| [date]/
@@ -183,7 +186,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
@@ -223,7 +226,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.
 

diff --git a/docs/content/docs/5.v9/2.guide/8.lang-switcher.md b/docs/content/docs/5.v9/2.guide/8.lang-switcher.md
@@ -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.