中间件

概述

本指南将带你一步步在你的 Next.js 应用中，使用 gt-next 内置的中间件添加 i18n 中间件路由和本地化路径。

什么是 i18n 中间件路由？

为每种语言创建新的路由有助于让你的网站更加友好，并提升 SEO 效果。 i18n 路由允许你将特定的 URL 与不同的语言环境关联起来。 例如，你可以为英文使用 /en/airplanes，为中文使用 /zh/airplanes，以此类推。

你还可以通过本地化路径进一步提升体验。 本地化路径是 i18n 路由的扩展，允许你为某个语言环境指定一个别名路径。 例如，你可以为英文指定 /en/airplanes，为中文指定 /zh/飞机，以此类推。

设置 i18n 路由

我们将带你通过两个简单的步骤，为你的 Next.js 应用添加 i18n 路由：

步骤 1：添加动态路由

在你的 app 文件夹中插入一个名为 [locale] 的目录（例如，app/[locale]）。 将你所有的页面和布局都放在这个目录下。

确保 app/ 目录下的所有特殊文件都嵌套在 app/[locale] 下。

步骤 2：添加 middleware 文件

在 Next.js 中，在根目录下创建一个名为 middleware.js（如果你使用 TypeScript，则为 .ts）的文件。 如果你使用 src/ 文件夹，请将其放在 src/middleware.js（或 .ts）中。 在文件中添加 createNextMiddleware() 函数。

import { createNextMiddleware } from 'gt-next/middleware'

export default createNextMiddleware();

export const config = {
  matcher: [
    /*
      * Match all request paths except for the ones starting with:
      * - api (API routes)
      * - _next (internal files)
      * - static files
      */
    "/((?!api|static|.*\\..*|_next).*)",
  ],
}

设置本地化路径

你可以通过中间件文件中的 pathConfig 选项来指定本地化路径。

export default createNextMiddleware({
  pathConfig: {
    // You can specify a shared path (optional)
    // This will create "/en/about" and "/zh/about"
    "/about": "/about",

    // Specify localized paths
    // This will create "/en/airplanes" and "/zh/飞机"
    "/airplanes": {
      "zh": "/飞机",
    }

    // Add dynamic path parameters
    // This will create "/en/airports/123" and "/zh/飞机机场/123"
    "/airports/[id]": {
      "zh": "/飞机机场/[id]",
    }
  },
});

在这个示例中，我们为 /en/about 创建了一个默认路径，并为 /en/airplanes 和 /en/airports/[id] 创建了本地化路径。 在中文中，这些路径将分别被映射为 /zh/about、/zh/飞机 和 /zh/飞机机场/[id]。

路由行为

默认语言前缀

默认情况下，你的 defaultLocale（即应用的默认语言）在网址中不会带有语言代码前缀。 例如，如果你的默认语言是 en，并且你有一个页面在 /about，那么英文页面将通过 /about 访问。 然而，在中文中，该页面将通过 /zh/about 访问。

如果你不希望有这种行为，可以在中间件配置中将 prefixDefaultLocale 设置为 false 来禁用。

语言检测与重定向

中间件会根据以下顺序检测用户的语言：(1) url 路径中的语言，(2) 来源页面的语言，(3) 浏览器的首选语言，(4) 最后是 defaultLocale。 然后，用户会被相应地重定向。

如果某个页面存在本地化版本，用户会被重定向到本地化的 url。 例如，/zh/airplanes 总是会重定向到 /zh/飞机。

边缘情况：没有语言前缀的本地化路径

如果你访问一个没有语言前缀的本地化路径（例如 /飞机），中间件会根据它认为你当前的语言为该路径加上前缀。

例如，访问 /飞机 只有在中间件明确识别你的语言为 zh 时才会重定向到 /zh/飞机。 这很好，但只在中间件认为你的语言是 zh 时有效。

否则，你的路径会加上你当前的语言前缀。 例如，如果中间件认为你的语言是 en，访问 /飞机 会重定向到 /en/飞机。 这将导致 404。

我们建议在项目中的任何链接都始终使用 defaultLocale 的路径。 这样总会自动重定向到正确的本地化路径。

<Link href="/about">About</Link>
<Link href="/planes">Planes</Link>
<Link href="/airports/123">Airport 123</Link>

如果你想明确链接到其他语言，可以使用本地化路径来实现。

<Link href="/zh/about">About in Chinese</Link>
<Link href="/zh/飞机">Planes in Chinese</Link>
<Link href="/zh/飞机机场/123">Airport 123 in Chinese</Link>

注意事项

• i18n 路由会改变应用程序的 URL 结构。每种语言都有自己的 URL。
• 需要 middleware 文件来处理路由逻辑。
• 你可以在 middleware 配置和 next 配置文件中指定支持的语言环境。

后续步骤

• 查看 createNextMiddleware() 的 API 文档。