跳到内容
构建你的应用路由国际化

国际化 (i18n) 路由

示例

Next.js 从 v10.0.0 版本开始内置了对国际化 (i18n) 路由的支持。你可以提供区域设置列表、默认区域设置和特定于域的区域设置，Next.js 将自动处理路由。

i18n 路由支持目前旨在补充现有的 i18n 库解决方案，例如 react-intl、 react-i18next、 lingui、 rosetta、 next-intl、 next-translate、 next-multilingual、 tolgee、 paraglide-next、 next-intlayer 等，通过简化路由和区域设置解析。

开始上手

要开始使用，请将 i18n 配置添加到你的 next.config.js 文件中。

区域设置是 UTS 区域设置标识符，这是一种用于定义区域设置的标准化格式。

通常，区域设置标识符由语言、区域和脚本组成，并用破折号分隔：language-region-script。区域和脚本是可选的。一个例子：

  • en-US - 美国英语
  • nl-NL - 荷兰荷兰语
  • nl - 荷兰语，无特定区域

如果用户区域设置是 nl-BE 且未在你的配置中列出，他们将被重定向到 nl（如果可用），否则重定向到默认区域设置。如果你不打算支持一个国家的所有地区，那么包含将充当后备的国家/地区区域设置是一个好的做法。

next.config.js
module.exports = {
  i18n: {
    // These are all the locales you want to support in
    // your application
    locales: ['en-US', 'fr', 'nl-NL'],
    // This is the default locale you want to be used when visiting
    // a non-locale prefixed path e.g. `/hello`
    defaultLocale: 'en-US',
    // This is a list of locale domains and the default locale they
    // should handle (these are only required when setting up domain routing)
    // Note: subdomains must be included in the domain value to be matched e.g. "fr.example.com".
    domains: [
      {
        domain: 'example.com',
        defaultLocale: 'en-US',
      },
      {
        domain: 'example.nl',
        defaultLocale: 'nl-NL',
      },
      {
        domain: 'example.fr',
        defaultLocale: 'fr',
        // an optional http field can also be used to test
        // locale domains locally with http instead of https
        http: true,
      },
    ],
  },
}

区域设置策略

有两种区域设置处理策略：子路径路由和域名路由。

子路径路由

子路径路由将区域设置放在 URL 路径中。

next.config.js
module.exports = {
  i18n: {
    locales: ['en-US', 'fr', 'nl-NL'],
    defaultLocale: 'en-US',
  },
}

使用上述配置，en-US、fr 和 nl-NL 将可用于路由，并且 en-US 是默认区域设置。如果你有一个 pages/blog.js 文件，则以下 URL 将可用：

  • /blog
  • /fr/blog
  • /nl-nl/blog

默认区域设置没有前缀。

域名路由

通过使用域名路由，你可以配置从不同域名提供区域设置。

next.config.js
module.exports = {
  i18n: {
    locales: ['en-US', 'fr', 'nl-NL', 'nl-BE'],
    defaultLocale: 'en-US',
 
    domains: [
      {
        // Note: subdomains must be included in the domain value to be matched
        // e.g. www.example.com should be used if that is the expected hostname
        domain: 'example.com',
        defaultLocale: 'en-US',
      },
      {
        domain: 'example.fr',
        defaultLocale: 'fr',
      },
      {
        domain: 'example.nl',
        defaultLocale: 'nl-NL',
        // specify other locales that should be redirected
        // to this domain
        locales: ['nl-BE'],
      },
    ],
  },
}

例如，如果你有 pages/blog.js 文件，则以下 URL 将可用：

  • example.com/blog
  • www.example.com/blog
  • example.fr/blog
  • example.nl/blog
  • example.nl/nl-BE/blog

自动区域设置检测

当用户访问应用程序根目录（通常是 /）时，Next.js 将尝试根据 Accept-Language 标头和当前域名自动检测用户首选的区域设置。

如果检测到除默认区域设置之外的其他区域设置，则用户将被重定向到以下位置之一：

  • 当使用子路径路由时：带有区域设置前缀的路径
  • 当使用域名路由时：将该区域设置指定为默认设置的域名

当使用域名路由时，如果 Accept-Language 标头为 fr;q=0.9 的用户访问 example.com，他们将被重定向到 example.fr，因为该域名默认处理 fr 区域设置。

当使用子路径路由时，用户将被重定向到 /fr。

为默认区域设置添加前缀

使用 Next.js 12 和 中间件，我们可以使用 变通方法 为默认区域设置添加前缀。

例如，这是一个支持多种语言的 next.config.js 文件。请注意，已有意添加 "default" 区域设置。

next.config.js
module.exports = {
  i18n: {
    locales: ['default', 'en', 'de', 'fr'],
    defaultLocale: 'default',
    localeDetection: false,
  },
  trailingSlash: true,
}

接下来，我们可以使用 中间件 添加自定义路由规则。

middleware.ts
import { NextRequest, NextResponse } from 'next/server'
 
const PUBLIC_FILE = /\.(.*)$/
 
export async function middleware(req: NextRequest) {
  if (
    req.nextUrl.pathname.startsWith('/_next') ||
    req.nextUrl.pathname.includes('/api/') ||
    PUBLIC_FILE.test(req.nextUrl.pathname)
  ) {
    return
  }
 
  if (req.nextUrl.locale === 'default') {
    const locale = req.cookies.get('NEXT_LOCALE')?.value || 'en'
 
    return NextResponse.redirect(
      new URL(`/${locale}${req.nextUrl.pathname}${req.nextUrl.search}`, req.url)
    )
  }
}

此 中间件 跳过为 API 路由 和 public 文件（如字体或图像）添加默认前缀。如果向默认区域设置发出请求，我们将重定向到我们的前缀 /en。

禁用自动区域设置检测

可以使用以下方式禁用自动区域设置检测：

next.config.js
module.exports = {
  i18n: {
    localeDetection: false,
  },
}

当 localeDetection 设置为 false 时，Next.js 将不再根据用户的首选区域设置自动重定向，并且仅提供从基于区域设置的域名或区域设置路径检测到的区域设置信息，如上所述。

访问区域设置信息

你可以通过 Next.js 路由器访问区域设置信息。例如，使用 useRouter() hook，以下属性可用：

  • locale 包含当前活动的区域设置。
  • locales 包含所有配置的区域设置。
  • defaultLocale 包含配置的默认区域设置。

当使用 getStaticProps 或 getServerSideProps 预渲染 页面时，区域设置信息在提供给 上下文 的函数中提供。

当利用 getStaticPaths 时，配置的区域设置在函数的上下文参数的 locales 下提供，配置的 defaultLocale 在 defaultLocale 下提供。

区域设置之间过渡

你可以使用 next/link 或 next/router 在区域设置之间过渡。

对于 next/link，可以提供 locale 属性以从当前活动的区域设置过渡到不同的区域设置。如果未提供 locale 属性，则在客户端过渡期间使用当前活动的 locale。例如：

import Link from 'next/link'
 
export default function IndexPage(props) {
  return (
    <Link href="/another" locale="fr">
      To /fr/another
    </Link>
  )
}

当直接使用 next/router 方法时，你可以通过过渡选项指定应使用的 locale。例如：

import { useRouter } from 'next/router'
 
export default function IndexPage(props) {
  const router = useRouter()
 
  return (
    <div
      onClick={() => {
        router.push('/another', '/another', { locale: 'fr' })
      }}
    >
      to /fr/another
    </div>
  )
}

请注意，要处理仅切换 locale，同时保留所有路由信息，例如 动态路由 查询值或隐藏的 href 查询值，你可以将 href 参数作为对象提供：

import { useRouter } from 'next/router'
const router = useRouter()
const { pathname, asPath, query } = router
// change just the locale and maintain all other route information including href's query
router.push({ pathname, query }, asPath, { locale: nextLocale })

有关 router.push 的对象结构的更多信息，请参阅此处。

如果你的 href 已经包含区域设置，你可以选择不自动处理区域设置前缀：

import Link from 'next/link'
 
export default function IndexPage(props) {
  return (
    <Link href="/fr/another" locale={false}>
      To /fr/another
    </Link>
  )
}

Next.js 允许设置 NEXT_LOCALE=the-locale cookie，它优先于 accept-language 标头。可以使用语言切换器设置此 cookie，然后当用户返回站点时，当从 / 重定向到正确的区域设置位置时，它将利用 cookie 中指定的区域设置。

例如，如果用户在其 accept-language 标头中首选区域设置 fr，但设置了 NEXT_LOCALE=en cookie，则当访问 / 时，用户将被重定向到 en 区域设置位置，直到删除或过期 cookie。

搜索引擎优化

由于 Next.js 知道用户正在访问哪种语言，它将自动将 lang 属性添加到 <html> 标签。

Next.js 不知道页面的变体，因此你需要使用 next/head 添加 hreflang 元标记。你可以在 Google 网站管理员文档中了解有关 hreflang 的更多信息。

这如何与静态生成协同工作？

请注意，国际化路由不与 output: 'export' 集成，因为它不利用 Next.js 路由层。完全支持不使用 output: 'export' 的混合 Next.js 应用程序。

动态路由和 getStaticProps 页面

对于使用 getStaticProps 和 动态路由 的页面，要预渲染的页面的所有区域设置变体都需要从 getStaticPaths 返回。除了为 paths 返回的 params 对象之外，你还可以返回一个 locale 字段，指定要渲染的区域设置。例如：

pages/blog/[slug].js
export const getStaticPaths = ({ locales }) => {
  return {
    paths: [
      // if no `locale` is provided only the defaultLocale will be generated
      { params: { slug: 'post-1' }, locale: 'en-US' },
      { params: { slug: 'post-1' }, locale: 'fr' },
    ],
    fallback: true,
  }
}

对于 自动静态优化 和非动态 getStaticProps 页面，将为每个区域设置生成一个页面版本。这很重要，需要考虑，因为它可能会增加构建时间，具体取决于 getStaticProps 中配置了多少区域设置。

例如，如果你配置了 50 个区域设置，并且有 10 个非动态页面使用 getStaticProps，这意味着 getStaticProps 将被调用 500 次。在每次构建期间将生成 10 个页面的 50 个版本。

要减少使用 getStaticProps 的动态页面的构建时间，请使用 fallback 模式。这允许你仅从 getStaticPaths 返回最受欢迎的路径和区域设置，以便在构建期间进行预渲染。然后，Next.js 将在运行时按需构建其余页面。

自动静态优化的页面

对于 自动静态优化 的页面，将为每个区域设置生成一个页面版本。

非动态 getStaticProps 页面

对于非动态的 getStaticProps 页面，会为每个 locale 生成一个版本，如上所示。 getStaticProps 会在渲染的每个 locale 中被调用。如果您想选择不预渲染某个 locale，您可以从 getStaticProps 返回 notFound: true，这样该页面的这个变体将不会被生成。

export async function getStaticProps({ locale }) {
  // Call an external API endpoint to get posts.
  // You can use any data fetching library
  const res = await fetch(`https://.../posts?locale=${locale}`)
  const posts = await res.json()
 
  if (posts.length === 0) {
    return {
      notFound: true,
    }
  }
 
  // By returning { props: posts }, the Blog component
  // will receive `posts` as a prop at build time
  return {
    props: {
      posts,
    },
  }
}

i18n 配置的限制

  • locales：总共 100 个 locales
  • domains：总共 100 个 locale 域名项

须知：这些限制最初添加是为了防止在构建时出现潜在的 性能问题。您可以使用 Next.js 12 中的 中间件 通过自定义路由来规避这些限制。