Lzh on GitHub

自定义路由路径

自定义特定语言环境的路径名称。

在某些情况下，除了为 URL 添加语言环境前缀之外，你可能还需要翻译 URL。配置自定义路径有两种方法：通过 模块配置 或在每个 页面组件 内。

使用哪种方法是通过设置 customRoutes 选项 配置的，此选项默认为 'page'。不能同时使用这两种方法。

除非与 differentDomains 结合使用，否则在使用 'no_prefix' 策略 时不支持自定义路径。

模块配置

请确保将 customRoutes 选项设置为 'config'，并在 pages 选项中添加你的自定义路径：

nuxt.config.ts
export default defineNuxtConfig({
  i18n: {
    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)
        fr: '/a-propos', // -> accessible at /fr/a-propos
        es: '/sobre' // -> accessible at /es/sobre
      }
    }
  }
})

请注意，pages 对象中的每个键都应对应于 要本地化的路由的路由名称。

自定义路由路径 必须以 / 开头，并且 不得包含语言环境前缀。

你现在可以使用 localePath() 函数或 <NuxtLinkLocale> 组件，但请务必使用命名路由。例如，路由 /services/advanced 应该为 'services-advanced'：

<script setup>
const { t } = useI18n()
</script>

<template>
  <NuxtLinkLocale to="about"> {{ t('about') }} </NuxtLinkLocale>
  <NuxtLinkLocale to="services-advanced"> {{ t('advanced') }} </NuxtLinkLocale>
</template>

或者:

<script setup>
const { t } = useI18n()
const localePath = useLocalePath()
</script>

<template>
  <NuxtLink :to="localePath('about')"> {{ t('about') }} </NuxtLink>
  <NuxtLink :to="localePath('services-advanced')"> {{ t('advanced') }} </NuxtLink>
</template>
目前不支持将路径传递给 localePath()。

示例 1：基本 URL 本地化

你有一些路由，其 pages 目录如下：

Directory structure
-| pages/
---| parent/
-----| child.vue
---| parent.vue
嵌套/子路由依赖于存在一个与渲染子路由的文件夹同名的页面组件。 有关更多详细信息，请参阅 嵌套路由。

你需要按如下方式设置 pages 属性：

nuxt.config.ts
export default defineNuxtConfig({
  i18n: {
    customRoutes: 'config',
    pages: {
      parent: {
        en: '/parent',
        ca: '/pare'
      },
      'parent-child': {
        en: '/parent/child',
        ca: '/pare/fill'
      }
    }
  }
})
所有 URL 必须以 / 开头

Example 2: URL 部分本地化

你有一些路由，其 pages 目录如下：

Directory structure
-| pages/
---| about.vue
---| services/
-----| index.vue
-----| coaching.vue
-----| development/
-------| app.vue
-------| website.vue
-----| development.vue
---| services.vue

你需要按如下方式设置 pages 属性：

nuxt.config.ts
export default defineNuxtConfig({
  i18n: {
    customRoutes: 'config',
    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'
      }
    }
  }
})

如果某个语言环境缺少自定义路径，则使用 defaultLocale 自定义路径（如果已设置）。

示例 3：动态路由

假设你有一些动态路由，例如：

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

以下是如何在配置中配置这些特定页面：

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]'
        // ...
      }
    }
  }
})

definePageMeta

你可以在 definePageMeta() 中使用 i18n 属性为每个页面组件设置自定义路径。

pages/about.vue
<script setup>
definePageMeta({
  i18n: {
    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>

要为动态路由配置自定义路径，你需要像在 Nuxt 动态路由 中那样，在路径中使用双括号：

pages/articles/[name].vue
<script setup>
definePageMeta({
  i18n: {
    paths: {
      en: '/articles/[name]',
      es: '/artículo/[name]'
    }
  }
})
</script>

defineI18nRoute

此方法已弃用，推荐使用 definePageMeta()，并将在 v11 中移除。

你可以使用 defineI18nRoute() 编译器宏为每个页面组件设置自定义路径。

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>

要为动态路由配置自定义路径，你需要像在 Nuxt 动态路由 中那样，在路径中使用双括号：

pages/articles/[name].vue
<script setup>
defineI18nRoute({
  paths: {
    en: '/articles/[name]',
    es: '/artículo/[name]'
  }
})
</script>
defineI18nRoute() 编译器宏在构建时被 tree-shaken 掉，不包含在分发文件中。

动态路由参数

处理动态路由参数需要做更多的工作，因为你需要向 Nuxt i18n 模块 提供参数翻译。可组合函数 useSetI18nParams 可用于设置路由参数的翻译，这用于设置 SEO 标签以及更改由 <SwitchLocalePathLink> 渲染的路由。

switchLocalePath 将使用 setI18nParams 的翻译参数返回本地化路由，这可能会导致以前使用 switchLocalePath 渲染的链接出现水合问题。 请改用 <SwitchLocalePathLink> 组件，其路由在发送渲染响应之前会更新。

一个示例（将 slug 替换为适用的路由参数）：

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

请注意，对于像 [...pathMatch].vue 这样的特殊情况，对象键需要是 pathMatch。例如：

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

<template>
  <!-- pages/[...pathMatch].vue -->
</template>

请注意，一个包罗万象的路由被定义为一个数组。在这种情况下，只有一个元素，但如果你想使用子路径，例如 '/not-found/post'，请定义多个元素，如 ['not-found', 'post']。你需要定义多个，例如 ['not-found', 'post']。

Nuxt i18n 模块 不会为你重置参数翻译，这意味着如果你对不同的路由使用相同的参数，在这些路由之间导航可能会导致参数冲突。在这种情况下，请确保始终设置参数翻译。

definePageMeta({ name: '...' }) 注意事项

默认情况下，Nuxt 在构建时会覆盖生成的路由值，这在解析本地化路径时会破坏自定义命名路由（使用 definePageMeta() 设置 name）。

Nuxt v3.10 引入了实验性功能 scanPageMeta，在使用 Nuxt I18n 时，需要启用此功能才能使自定义命名路由工作。

此实验性功能可以按如下方式启用：

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    scanPageMeta: true
  }
})