NNext.js 中文网 GitHub

如何在 Next.js 中实现国际化

Next.js 内置支持国际化路由和语言检测。在此了解更多。

<details> <summary>示例</summary>

</details>

自 v10.0.0 起,Next.js 内置支持国际化(i18n)路由。你可以提供区域设置(locale)列表、默认区域设置以及特定于域名的区域设置,Next.js 将自动处理路由。

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

开始使用#

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

区域设置是 UTS Locale Identifiers,一种用于定义区域设置的标准化格式。

通常,区域设置标识符由语言、地区和文字三部分组成,用连字符分隔:language-region-script。地区和文字是可选的。例如:

  • en-US - 美国使用的英语
  • nl-NL - 荷兰使用的荷兰语
  • nl - 荷兰语,无特定地区

如果用户的区域设置为 nl-BE 且未在你的配置中列出,则会将其重定向到 nl(如果可用),否则重定向到默认区域设置。因此,如果你不打算支持一个国家的所有地区,最好包含可作为后备的国家级区域设置。

next.config.js
module.exports = {
  i18n: {
    // 这些是你想要在应用中支持的
    // 所有区域设置
    locales: ['en-US', 'fr', 'nl-NL'],
    // 这是访问非区域设置前缀路径(例如 `/hello`)时
    // 要使用的默认区域设置
    defaultLocale: 'en-US',
    // 这是区域设置域名列表及其应处理的默认区域设置
    // (仅在设置域名路由时才需要)
    // 注意:域名值中必须包含子域名才能进行匹配,例如 "fr.example.com"。
    domains: [
      {
        domain: 'example.com',
        defaultLocale: 'en-US',
      },
      {
        domain: 'example.nl',
        defaultLocale: 'nl-NL',
      },
      {
        domain: 'example.fr',
        defaultLocale: 'fr',
        // 还可以使用可选的 http 字段在本地
        // 用 http 而非 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: [
      {
        // 注意:域名值中必须包含子域名才能进行匹配
        // 例如,如果预期主机名是 www.example.com,则应使用 www.example.com
        domain: 'example.com',
        defaultLocale: 'en-US',
      },
      {
        domain: 'example.fr',
        defaultLocale: 'fr',
      },
      {
        domain: 'example.nl',
        defaultLocale: 'nl-NL',
        // 指定应重定向到
        // 此域名的其他区域设置
        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 和 Proxy,我们可以通过一种变通方法为默认区域设置添加前缀。

例如,以下是一个支持几种语言的 next.config.js 文件。请注意,"default" 区域设置是有意添加的。

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

接下来,我们可以使用 Proxy 添加自定义路由规则:

proxy.ts
import { NextRequest, NextResponse } from 'next/server'

const PUBLIC_FILE = /\.(.*)$/

export async function proxy(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)
    )
  }
}

这个 Proxy 会跳过为 API Routes 和 public 文件(如字体或图片)添加默认前缀。如果请求指向默认区域设置,我们会重定向到带前缀的 /en。

禁用自动区域设置检测#

可以通过以下方式禁用自动区域设置检测:

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

当 localeDetection 设置为 false 时,Next.js 将不再根据用户偏好的区域设置自动重定向,而只会提供从基于区域设置的域名或区域设置路径中检测到的区域设置信息(如上所述)。

访问区域设置信息#

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

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

在使用 getStaticProps 或 getServerSideProps 预渲染页面时,区域设置信息会在传递给函数的 context 中提供。

使用 getStaticPaths 时,已配置的区域设置会在函数的 context 参数中的 locales 下提供,已配置的 defaultLocale 在 defaultLocale 下提供。

在区域设置之间切换#

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

对于 next/link,可以提供 locale 属性以从当前激活的区域设置切换到其他区域设置。如果未提供 locale 属性,则在客户端切换期间使用当前激活的 locale。例如:

jsx
import Link from 'next/link'

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

直接使用 next/router 方法时,你可以通过切换选项指定要使用的 locale。例如:

jsx
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 参数作为对象提供:

jsx
import { useRouter } from 'next/router'
const router = useRouter()
const { pathname, asPath, query } = router
// 仅更改区域设置,并保留所有其他路由信息,包括 href 的查询
router.push({ pathname, query }, asPath, { locale: nextLocale })

请参阅此处,了解 router.push 的对象结构更多信息。

如果你的 href 已经包含区域设置,可以选择退出自动处理区域设置前缀:

jsx
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 知道用户访问时使用的语言,它会自动为 <html> 标签添加 lang 属性。

Next.js 不知道页面的变体,因此你需要使用 next/head 添加 hreflang meta 标签。你可以在 Google Webmasters 文档中了解更多关于 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: [
      // 如果未提供 `locale`,则只生成 defaultLocale
      { 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 页面,会像上面一样为每个区域设置一个版本。getStaticProps 会随每个正在渲染的 locale 一起调用。如果你希望某个区域设置不参与预渲染,可以从 getStaticProps 返回 notFound: true,这样该页面变体将不会生成。

js
export async function getStaticProps({ locale }) {
  // 调用外部 API 端点以获取文章。
  // 你可以使用任何数据获取库
  const res = await fetch(`https://.../posts?locale=${locale}`)
  const posts = await res.json()

  if (posts.length === 0) {
    return {
      notFound: true,
    }
  }

  // 通过返回 { props: posts },Blog 组件
  // 将在构建时收到 `posts` 作为 prop
  return {
    props: {
      posts,
    },
  }
}

i18n 配置的限制#

  • locales:总计 100 个区域设置
  • domains:总计 100 个区域设置域名项

小知识:这些限制最初是为了防止潜在的构建时性能问题而添加的。在 Next.js 12 中,你可以使用 Proxy 通过自定义路由来绕过这些限制。

Next.js 中文网