指南

自定义路由路径

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

在某些情况下，您可能希望翻译 URL 除了将其前缀添加语言环境代码。配置自定义路径有两种方法，通过 模块配置 或在每个 页面组件 内部。

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

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

模块配置

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

nuxt.config.ts
export default defineNuxtConfig({
  i18n: {
    customRoutes: 'config', // 禁用自定义路由与页面组件
    pages: {
      about: {
        en: '/about-us', // -> 可访问 /about-us (没有前缀因为这是默认语言环境)
        fr: '/a-propos', // -> 可访问 /fr/a-propos
        es: '/sobre' // -> 可访问 /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 必须以 / 开头

示例 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': {
        // 参数需要在这里重新放回，就像您在 Nuxt 动态路由中一样
        // https://nuxt.com/docs/guide/directory-structure/pages#dynamic-routes
        ja: '/blog/tech/[date]/[slug]'
        // ...
      }
    }
  }
})

页面组件

对于更新到 v8.0.1 或更高版本的用户

路径参数解析已更改，以匹配 Nuxt 3 的路径参数解析，您需要更新自定义路径（例如，'/example/:param' 现在应为 '/example/[param]'）。

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

pages/about.vue
<script setup>
defineI18nRoute({
  paths: {
    en: '/about-us', // -> 可访问 /about-us (没有前缀因为这是默认语言环境)
    fr: '/a-propos', // -> 可访问 /fr/a-propos
    es: '/sobre' // -> 可访问 /es/sobre
  }
})
</script>

要为动态路由配置自定义路径，您需要在路径中使用双中括号，类似于您在 Nuxt 动态路由 中的用法：

pages/articles/[name
<script setup>
defineI18nRoute({
  paths: {
    en: '/articles/[name]',
    es: '/artículo/[name]'
  }
})
</script>
defineI18nRoute() 编译器宏在构建时会被树摇出，不会包含在 dist 文件中。

动态路由参数

处理动态路由参数需要更多的工作，因为您需要为 Nuxt i18n 模块 提供参数翻译。可组合的 useSetI18nParams 可用于设置路由参数的翻译，这用于设置 SEO 标签以及更改 switchLocalePath 返回的路由。

在 SSR 期间，设置 i18n 参数的时机和位置很重要，因为在 SSR 中没有响应性。

已经渲染的组件不会因页面和组件下游的更改而更新。相反，这些链接在客户端的水合过程中更新，在大多数情况下，这不会造成问题。

但是，对于 SEO 标签，这些在 SSR 期间可以正确更新，无论何时何地设置 i18n 参数。

查看实验性的 switchLocalePathLinkSSR 功能，该功能与 <SwitchLocalePathLink> 组件结合使用，可以在 SSR 期间正确渲染链接，无论何时何地使用。

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

<script setup>
// 从 API 获取产品...（红色马克杯）

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

运行时钩子

Nuxt i18n 模块提供运行时钩子，可以根据应用的语言执行特定任务。

忽略本地化路由

根据页面组件自定义本地化路由排除设置。