开始使用 Intlayer 和 Next.js 14 进行国际化（i18n）
什么是 Intlayer？
Intlayer 是一个创新的开源国际化（i18n）库，旨在简化现代Web应用程序中的多语言支持。Intlayer 无缝集成了最新的 Next.js 14 框架，包括其强大的 App Router。它经过优化以与 Server Components 配合使用，以实现高效渲染，并且与 Turbopack（从 Next.js >= 15 开始）完全兼容。
使用 Intlayer，您可以：
- 轻松管理翻译，使用声明性字典在组件级别进行管理。
- 动态本地化元数据、路由和内容。
- 在客户端和服务器端组件中访问翻译。
- 确保 TypeScript 支持，生成的类型改善了自动完成和错误检测。
- 利用高级功能，如动态本地检测和切换。
Intlayer 兼容 Next.js 12、13、14 和 15。如果您使用的是 Next.js Page Router，可以参考此 指南。有关 Next.js 15（包含或不包含 turbopack），请参见此 指南。
在 Next.js 应用程序中设置 Intlayer 的逐步指南
步骤 1：安装依赖项
使用 npm 安装必要的包：
npm install intlayer next-intlayerintlayer
next-intlayer
将 Intlayer 与 Next.js 集成的包。它提供了用于 Next.js 国际化的上下文提供者和钩子。此外，它还包括 Next.js 插件用于将 Intlayer 集成到 Webpack 或 Turbopack 中，并提供用于检测用户首选语言、管理cookie和处理URL重定向的中间件。
步骤 2：配置您的项目
创建一个配置文件来配置您应用程序的语言：
import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = { internationalization: { locales: [ Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH, // 其他语言 ], defaultLocale: Locales.ENGLISH, },};export default config;通过此配置文件，您可以设置本地化的 URL、中间件重定向、cookie 名称、内容声明的位置和扩展名、禁用 Intlayer 在控制台中的日志等。有关可用参数的完整列表，请参见 配置文档。
步骤 3：在 Next.js 配置中集成 Intlayer
配置您的 Next.js 设置以使用 Intlayer：
import { withIntlayer } from "next-intlayer/server";/** @type {import('next').NextConfig} */const nextConfig = {};export default withIntlayer(nextConfig);withIntlayer() Next.js 插件用于将 Intlayer 与 Next.js 集成。它确保在开发模式下构建内容声明文件并监控它们。它在 Webpack 或 Turbopack 环境中定义 Intlayer 环境变量。此外，它提供别名以优化性能，并确保与服务器组件的兼容性。
步骤 4：配置用于语言检测的中间件
设置中间件以检测用户首选的语言：
export { intlayerMiddleware as middleware } from "next-intlayer/middleware";export const config = { matcher: "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",};intlayerMiddleware 用于检测用户首选的语言并将其重定向到适当的 URL，如在 配置 中指定。此外，它启用了将用户首选语言保存到 cookie 中的功能。
根据您的应用程序路由调整 matcher 参数。有关更多详细信息，请参阅 Next.js 文档中关于配置匹配器的内容。
步骤 5：定义动态语言路由
从 RootLayout 中删除所有内容，并用以下代码替换：
import type { PropsWithChildren, FC } from "react";import "./globals.css";const RootLayout: FC<PropsWithChildren> = ({ children }) => children;export default RootLayout;要实现动态路由，通过添加新的布局在您的 [locale] 目录中提供语言路径：
import type { Next14LayoutIntlayer } from "next-intlayer";import { Inter } from "next/font/google";import { getHTMLTextDir } from "intlayer";const inter = Inter({ subsets: ["latin"] });const LocaleLayout: Next14LayoutIntlayer = ({ children, params: { locale },}) => ( <html lang={locale} dir={getHTMLTextDir(locale)}> <body className={inter.className}>{children}</body> </html>);export default LocaleLayout;[locale] 路径段用于定义语言。例如：/en-US/about 将引用 en-US，而 /fr/about 将引用 fr。
然后，在您的应用程序布局中实现 generateStaticParams 函数。
export { generateStaticParams } from "next-intlayer"; // 插入行const LocaleLayout: Next14LayoutIntlayer = ({ children, params: { locale },}) => { /*... 其余代码*/};export default LocaleLayout;generateStaticParams 确保您的应用程序预构建所有语言所需的页面，减少运行时计算，提高用户体验。有关更多详细信息，请参阅 Next.js 文档中关于 generateStaticParams 的内容。
步骤 6：声明您的内容
创建和管理您的内容声明，以存储翻译：
import { t, type DeclarationContent } from "intlayer";const pageContent = { key: "page", content: { getStarted: { main: t({ en: "Get started by editing", fr: "Commencez par éditer", es: "Comience por editar", }), pageLink: "src/app/page.tsx", }, },} satisfies DeclarationContent;export default pageContent;您的内容声明可以在您的应用程序中的任何地方定义，只要它们包含在 contentDir 目录中（默认情况下为 ./src）。并且匹配内容声明文件扩展名（默认情况下为 .content.{ts,tsx,js,jsx,mjs,cjs}）。 有关更多详细信息，请参阅 内容声明文档。
步骤 7：在您的代码中利用内容
在应用程序的整个地方访问您的内容字典：
import { ClientComponentExample } from "@components/ClientComponentExample";import { ServerComponentExample } from "@components/ServerComponentExample";import { type Next14PageIntlayer, IntlayerClientProvider } from "next-intlayer";import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";const Page: Next14PageIntlayer = ({ params: { locale } }) => { const content = useIntlayer("page", locale); return ( <> <p> {content.getStarted.main} <code>{content.getStarted.pageLink}</code> </p> <IntlayerServerProvider locale={locale}> <IntlayerClientProvider locale={locale}> <ServerComponentExample /> <ClientComponentExample /> </IntlayerClientProvider> </IntlayerServerProvider> </> );};export default Page;- IntlayerClientProvider 用于为客户端组件提供语言。它可以放置在任何父组件中，包括布局。然而，建议将其放置在布局中，因为 Next.js 在页面之间共享布局代码，使其更加高效。通过在布局中使用 IntlayerClientProvider，您避免为每个页面重新初始化它，从而提高性能并保持整个应用程序中的本地化上下文一致性。
IntlayerServerProvider 用于为服务器子组件提供语言。它不能在布局中设置。
布局和页面不能共享一个公共的服务器上下文，因为服务器上下文系统基于每个请求的数据存储（通过 React 的缓存 机制），导致每个“上下文”在应用程序的不同部分被重建。将提供者放在共享布局中会破坏这种隔离，阻止服务器上下文值正确传播到您的服务器组件。
"use client";import type { FC } from "react";import { useIntlayer } from "next-intlayer";const ClientComponentExample: FC = () => { const content = useIntlayer("client-component-example"); // 创建相关内容声明 return ( <div> <h2>{content.title} </h2> <p>{content.content}</p> </div> );};import type { FC } from "react";import { useIntlayer } from "next-intlayer/server";const ServerComponentExample: FC = () => { const content = useIntlayer("server-component-example"); // 创建相关内容声明 return ( <div> <h2>{content.title} </h2> <p>{content.content}</p> </div> );};如果您想在 string 属性中使用您的内容，例如 alt、title、href、aria-label 等，您必须调用该函数的值，例如：
jsx<img src={content.image.src.value} alt={content.image.value} />
要了解有关 useIntlayer 钩子的更多信息，请参阅 [文档](https
如果您有改善此文档的想法，请随时通过在GitHub上提交拉取请求来贡献。
文档的 GitHub 链接