Intlayer 兼容 Next.js 12、13、14、15 和 16。如果您使用 Next.js Pages Router，可以参考此指南。区域设置路由对于 SEO、Bundle 大小和性能很有用。如果不需要，可以参考这个指南。对于带有 App Router 的 Next.js 12、13、14 和 15，请参阅此指南。

捆绑尺寸

不要将大量 JSON 文件加载到页面中，而只需加载必要的内容。 Intlayer 有助于将捆绑包和页面大小减少多达 50%。

可维护性

确定应用程序内容的范围有利于大型应用程序的维护。您可以复制或删除单个功能文件夹，而无需承担检查整个内容代码库的精神负担。此外，Intlayer 具有完全类型化 (fully typed)，以确保您的内容的准确性。

人工智能代理

共置内容减少大型语言模型 (LLM) 所需的上下文。 Intlayer 还附带了一套工具，例如用于测试缺失翻译的 CLI、LSP、MCP 和 agent技能，使 AI 代理的开发者体验 (DX) 更加流畅。

自动化

使用您选择的法学硕士，通过自动化在 CI/CD 管道中进行翻译，而费用由您的 AI 提供商承担。 Intlayer 还提供了一个编译器来自动提取内容，以及一个网络平台来帮助在后台翻译。

表现

将大量 JSON 文件连接到组件可能会导致性能和反应性问题。 Intlayer 可在构建时 (build time)优化您的内容加载。

无需开发即可扩展

Intlayer 不仅仅是一个 i18n 解决方案，还提供了一个自托管的可视化编辑器和一个完整的 CMS 来帮助您管理多语言内容实时，与译员、文案人员和其他团队成员无缝协作。内容可以本地和/或远程存储。

在 Next.js 应用中设置 Intlayer 的逐步指南

第一步：安装依赖

使用 npm 安装所需的包：

bash

复制代码

复制代码到剪贴板

npm install intlayer next-intlayernpx intlayer init

npm install intlayer next-intlayernpx intlayer init

intlayer

核心包，提供用于配置管理、翻译、内容声明、转译以及CLI 命令的国际化工具。
next-intlayer

将 Intlayer 与 Next.js 集成的包。它为 Next.js 的国际化提供了 context providers（上下文提供者）和 hooks（钩子）。此外，它还包含用于将 Intlayer 集成到 Webpack 或 Turbopack 的 Next.js 插件，以及用于检测用户首选 locale、管理 cookies 和处理 URL 重定向的 proxy。

配置您的项目

下面是我们将创建的最终结构：

bash

复制代码

复制代码到剪贴板

.├── src│   ├── app│   │   ├── layout.tsx│   │   ├── page.content.ts│   │   └── page.tsx│   ├── components│   │   ├── clientComponentExample│   │   │   ├── client-component-example.content.ts│   │   │   └── ClientComponentExample.tsx│   │   ├── localeSwitcher│   │   │   ├── localeSwitcher.content.ts│   │   │   └── LocaleSwitcher.tsx│   │   └── serverComponentExample│   │       ├── server-component-example.content.ts│   │       └── ServerComponentExample.tsx│   └── proxy.ts├── intlayer.config.ts├── next.config.ts├── package.json└── tsconfig.json

.├── src│   ├── app│   │   ├── layout.tsx│   │   ├── page.content.ts│   │   └── page.tsx│   ├── components│   │   ├── clientComponentExample│   │   │   ├── client-component-example.content.ts│   │   │   └── ClientComponentExample.tsx│   │   ├── localeSwitcher│   │   │   ├── localeSwitcher.content.ts│   │   │   └── LocaleSwitcher.tsx│   │   └── serverComponentExample│   │       ├── server-component-example.content.ts│   │       └── ServerComponentExample.tsx│   └── proxy.ts├── intlayer.config.ts├── next.config.ts├── package.json└── tsconfig.json

如果你不想使用区域路由，intlayer 可以作为一个简单的 provider / hook 来使用。更多细节参见本指南。

创建一个配置文件来配置应用的语言：

intlayer.config.ts

复制代码

复制代码到剪贴板

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // 你的其他语言
    ],
    defaultLocale: Locales.ENGLISH,
  },
  routing: {
    mode: "search-params", // 或 `no-prefix` - 对中间件检测有用
  },
};

export default config;

通过此配置文件，您可以设置本地化 URL、代理重定向、cookie 名称、内容声明的位置和扩展名、在控制台禁用 Intlayer 日志等。有关可用参数的完整列表，请参阅配置文档。

声明您的内容

创建并管理您的内容声明以存储翻译：

src/app/metadata.content.ts

复制代码

复制代码到剪贴板

import { t, type Dictionary } from "intlayer";
import { Metadata } from "next";

const metadataContent = {
  key: "metadata",
  content: {
    title: t({
      zh: "我的项目标题",
      en: "My Project Title",
      fr: "Le Titre de mon Projet",
      es: "El Título de mi Proyecto",
    }),

    description: t({
      zh: "了解我们创新的平台，旨在简化您的工作流程并提高生产力。",
      en: "Discover our innovative platform designed to streamline your workflow and boost productivity.",
      zh: "探索我们的创新平台，旨在简化您的工作流程并提升生产力。",
      fr: "Découvrez notre plateforme innovante conçue pour simplifier votre flux de travail et booster votre productivité.",
      es: "Descubra nuestra plataforma innovadora diseñada para simplificar su flujo de trabajo y aumentar su productividad.",
    }),

    keywords: t({
      zh: ["创新", "生产力", "工作流程", "SaaS"],
      en: ["innovation", "productivity", "workflow", "SaaS"],
      fr: ["innovation", "productivité", "flux de travail", "SaaS"],
      es: ["innovación", "productividad", "flujo de trabajo", "SaaS"],
    }),
  },
} as Dictionary<Metadata>;

export default metadataContent;

src/app/page.content.ts

复制代码

复制代码到剪贴板

import { t, type Dictionary } from "intlayer";

const pageContent = {
  key: "page",
  content: {
    getStarted: {
      main: t({
        zh: "通过编辑开始",
        en: "Get started by editing",
        fr: "Commencez par éditer",
        es: "Comience por editar",
      }),
      pageLink: "src/app/page.tsx",
    },
  },
} satisfies Dictionary;

export default pageContent;

你的内容声明可以在应用的任何位置定义，只要它们被包含到 contentDir 目录（默认 ./src）中。并且与内容声明文件扩展名匹配（默认 .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}）。

有关详细信息，请参阅内容声明文档。

在代码中使用内容

在应用程序中随处访问你的内容字典：

src/app/page.tsx

复制代码

复制代码到剪贴板

import type { FC } from "react";
import { ClientComponentExample } from "@components/clientComponentExample/ClientComponentExample";
import { ServerComponentExample } from "@components/serverComponentExample/ServerComponentExample";
import {
  IntlayerServerProvider,
  useIntlayer,
  getLocale,
} from "next-intlayer/server";
import { NextPage } from "next";
import { headers, cookies } from "next/headers";

const PageContent: FC = () => {
  const content = useIntlayer("page");

  return (
    <>
      <p>{content.getStarted.main}</p>
      <code>{content.getStarted.pageLink}</code>
    </>
  );
};

const Page: NextPage = async () => {
  // 在 Next.js 15+ 中等待 headers 和 cookies
  const headerList = await headers();
  const cookieList = await cookies();

  const locale = await getLocale({
    // 首先检查 intlayer cookie（默认: 'INTLAYER_LOCALE'）
    getCookie: (name) => cookieList.get(name)?.value,

    // 然后检查 intlayer header（默认：'x-intlayer-locale'）
    // 最后检查 accept-language header（'accept-language'）
    getHeader: (name) => headerList.get(name),
  });

  return (
    <IntlayerServerProvider locale={locale}>
      <PageContent />
      <ServerComponentExample />
      <ClientComponentExample />
    </IntlayerServerProvider>
  );
};

export default Page;

IntlayerClientProvider 用于将 locale 提供给客户端组件。它可以放在任何父组件中，包括 layout。然而，建议将其放在 layout 中，因为 Next.js 在页面之间会共享 layout 代码，这样更高效。将 IntlayerClientProvider 放在 layout 中可以避免为每个页面重新初始化，从而提高性能并在整个应用中保持一致的本地化上下文。
IntlayerServerProvider 用于将 locale 提供给服务端子组件。它不能设置在 layout 中。

Layout 和 page 不能共享同一个 server context，因为 server context 系统基于每次请求的数据存储（通过 React's cache 机制），导致每个 "context" 会为应用的不同部分被重新创建。将 provider 放在共享 layout 中会破坏此隔离，阻止 server context 值正确传播到你的 server components。

src/components/clientComponentExample/ClientComponentExample.tsx

复制代码

复制代码到剪贴板

"use client";

import type { FC } from "react";
import { useIntlayer } from "next-intlayer";

export const ClientComponentExample: FC = () => {
  const content = useIntlayer("client-component-example"); // 创建相关内容声明

  return (
    <div>
      <h2>{content.title}</h2>
      <p>{content.content}</p>
    </div>
  );
};

src/components/serverComponentExample/ServerComponentExample.tsx

复制代码

复制代码到剪贴板

import type { FC } from "react";
import { useIntlayer } from "next-intlayer/server";

export 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 等）中使用内容，可以使用函数的值，例如：

html

复制代码

复制代码到剪贴板

<img src="{content.image.src.value}" alt="{content.image.value}" /><img src="{content.image.src.toString()}" alt="{content.image.toString()}" /><img src="{String(content.image.src)}" alt="{String(content.image)}" />

<img src="{content.image.src.value}" alt="{content.image.value}" /><img src="{content.image.src.toString()}" alt="{content.image.toString()}" /><img src="{String(content.image.src)}" alt="{String(content.image)}" />

若要了解有关 useIntlayer hook 的更多信息，请参阅文档。

配置 Proxy 以进行 locale 检测

设置 Proxy 以检测用户的首选 locale：

src/proxy.ts

复制代码

复制代码到剪贴板

export { intlayerProxy as proxy } from "next-intlayer/proxy";

export const config = {
  matcher:
    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
};

intlayerProxy 用于检测用户偏好的 locale，并根据配置将用户重定向到相应的 URL。除此之外，它还可以将用户偏好的 locale 保存在 cookie 中。

如果需要将多个代理串联在一起（例如将 intlayerProxy 与身份验证或自定义代理一起使用），Intlayer 现在提供了一个名为 multipleProxies 的辅助函数。

复制代码

复制代码到剪贴板

import { multipleProxies, intlayerProxy } from "next-intlayer/proxy";import { customProxy } from "@utils/customProxy";export const proxy = multipleProxies([intlayerProxy, customProxy]);

import { multipleProxies, intlayerProxy } from "next-intlayer/proxy";import { customProxy } from "@utils/customProxy";export const proxy = multipleProxies([intlayerProxy, customProxy]);

更改您内容的语言

要在 Next.js 中更改内容的语言，推荐的方法是使用 Link 组件将用户重定向到相应的本地化页面。Link 组件支持页面预取，这有助于避免整页重新加载。

src/components/localeSwitcher/LocaleSwitcher.tsx

复制代码

复制代码到剪贴板

"use client";

import type { FC } from "react";
import { Locales, getHTMLTextDir, getLocaleName } from "intlayer";
import { useLocale } from "next-intlayer";

export const LocaleSwitcher: FC = () => {
  const { locale, availableLocales, setLocale } = useLocale();

  return (
    <div>
      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
      <div id="localePopover" popover="auto">
        {availableLocales.map((localeItem) => (
          <button
            key={localeItem}
            aria-current={locale === localeItem ? "page" : undefined}
            onClick={() => setLocale(localeItem)}
          >
            <span>
              {/* Locale（例如：FR） */}
              {localeItem}
            </span>
            <span>
              {/* 以该语言自身的 Locale 表示的语言名称（例如：Français） */}
              {getLocaleName(localeItem, locale)}
            </span>
            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
              {/* 以当前 Locale 表示的语言名称, 例如：当当前 locale 设置为 Locales.SPANISH 时显示：Francés */}
              {getLocaleName(localeItem)}
            </span>
            <span dir="ltr" lang={Locales.ENGLISH}>
              {/* 以英语显示的语言 - 例如 French */}
              {getLocaleName(localeItem, Locales.ENGLISH)}
            </span>
          </button>
        ))}
      </div>
    </div>
  );
};

另一种方法是使用 useLocale hook 提供的 setLocale 函数。此函数不会允许预获取页面。有关更多详细信息，请参阅 useLocale hook 文档。

文档参考：

useLocale hook
getLocaleName hook
getLocalizedUrl hook
getHTMLTextDir hook
hrefLang attribute
lang attribute
dir attribute`
aria-current attribute`

（可选）步骤 9：在 Server Actions 中获取当前 locale

如果你需要在 Server Action 中使用活动 locale（例如，用于本地化电子邮件或运行与 locale 相关的逻辑），请从 next-intlayer/server 调用 getLocale：

src/app/actions/getLocale.ts

复制代码

复制代码到剪贴板

"use server";import { getLocale } from "next-intlayer/server";export const myServerAction = async () => {  const locale = await getLocale();  // 使用该 locale 执行一些操作};

"use server";import { getLocale } from "next-intlayer/server";export const myServerAction = async () => {  const locale = await getLocale();  // 使用该 locale 执行一些操作};

getLocale 函数采用级联策略来确定用户的语言环境：

首先，它会检查请求头中是否存在可能由代理设置的 locale 值
如果在请求头中未找到 locale，则查找存储在 cookies 中的 locale
如果未找到 cookie，它会尝试从用户的浏览器设置中检测首选语言
最后，它会回退到应用程序配置的默认 locale
这可确保基于可用上下文选择最合适的 locale。

10
优化你的 bundle 大小

在使用 next-intlayer 时，字典默认会被包含到每个页面的 bundle 中。为了优化 bundle 大小，Intlayer 提供了一个可选的 SWC 插件，它使用宏智能替换 useIntlayer 调用。这样只有实际使用这些字典的页面的 bundle 才会包含相应字典。

要启用此优化，请安装 @intlayer/swc 包。安装后，next-intlayer 会自动检测并使用该插件：
bash
复制代码
复制代码到剪贴板
npm install @intlayer/swc --save-dev
npm install @intlayer/swc --save-dev
注意：此优化仅适用于 Next.js 13 及更高版本。

注意：该包默认不安装，因为 SWC 插件在 Next.js 中仍然是实验性的。将来可能会发生变化。

注意：如果你将选项设置为 importMode: 'dynamic' 或 importMode: 'fetch'，它将依赖 Suspense，因此你必须在一个 Suspense 边界中包裹你的 useIntlayer 调用。这意味着你不能在页面 / 布局组件的顶层直接使用 useIntlayer。

第 3 步：在 Next.js 配置中集成 Intlayer

配置您的 Next.js 设置以使用 Intlayer：

next.config.ts

复制代码

复制代码到剪贴板

import type { NextConfig } from "next";
import { withIntlayer } from "next-intlayer/server";

const nextConfig: NextConfig = {
  /* 在此处填写配置选项 */
};

export default withIntlayer(nextConfig);

withIntlayer() Next.js 插件用于将 Intlayer 集成到 Next.js 中。它负责构建内容声明文件，并在开发模式下监视这些文件。它会在 Webpack 或 Turbopack 环境中定义 Intlayer 的环境变量。此外，它还提供别名以优化性能，并确保与 server components 的兼容性。

withIntlayer() 函数是一个返回 Promise 的函数。它允许在构建开始前准备 intlayer 字典。如果你想与其他插件一起使用它，可以对其使用 await。示例：
ts
复制代码
复制代码到剪贴板
const nextConfig = await withIntlayer(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;
const nextConfig = await withIntlayer(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;
如果你想以同步方式使用它，可以使用 withIntlayerSync() 函数。示例：
ts
复制代码
复制代码到剪贴板
const nextConfig = withIntlayerSync(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;
const nextConfig = withIntlayerSync(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;
Intlayer 会根据命令行标志 --webpack、--turbo 或 --turbopack 以及你当前的 Next.js 版本自动检测项目是使用 webpack 还是 Turbopack。

自 next>=16 起，如果你使用 Rspack，必须通过禁用 Turbopack 明确强制 Intlayer 使用 webpack 配置：
ts
复制代码
复制代码到剪贴板
withRspack(withIntlayer(nextConfig, { enableTurbopack: false }));
withRspack(withIntlayer(nextConfig, { enableTurbopack: false }));

第4步：定义动态 locale 路由

从 RootLayout 中删除所有内容，并用下面的代码替换：

src/app/layout.tsx

复制代码

复制代码到剪贴板

import type { Metadata } from "next";
import type { ReactNode } from "react";
import "./globals.css";
import { IntlayerClientProvider, LocalPromiseParams } from "next-intlayer";
import { getHTMLTextDir, getIntlayer } from "intlayer";
import { getLocale } from "next-intlayer/server";
export { generateStaticParams } from "next-intlayer";

export const generateMetadata = async (): Promise<Metadata> => {
  const locale = await getLocale();
  const { title, description, keywords } = getIntlayer("metadata", locale);

  return {
    title,
    description,
    keywords,
  };
};

const RootLayout = async ({
  children,
}: Readonly<{
  children: ReactNode;
}>) => {
  const locale = await getLocale();

  return (
    <html lang={locale} dir={getHTMLTextDir(locale)}>
      <IntlayerClientProvider defaultLocale={locale}>
        <body>{children}</body>
      </IntlayerClientProvider>
    </html>
  );
};

export default RootLayout;

在 Turbopack 上监视字典更改

当使用 Turbopack 作为通过 next dev 命令运行的开发服务器时，字典更改默认不会被自动检测。

这个限制是因为 Turbopack 无法并行运行 webpack 插件来监视内容文件的更改。为了解决这个问题，你需要使用 intlayer watch 命令同时运行开发服务器和 Intlayer 构建监视器。

package.json

复制代码

复制代码到剪贴板

{  // ... 你现有的 package.json 配置  "scripts": {    // ... 你现有的 scripts 配置    "dev": "intlayer watch --with 'next dev'",  },}

{  // ... 你现有的 package.json 配置  "scripts": {    // ... 你现有的 scripts 配置    "dev": "intlayer watch --with 'next dev'",  },}

如果你使用的是 next-intlayer@<=6.x.x，你需要保留 --turbopack 标志以使 Next.js 16 应用程序能与 Turbopack 正常工作。我们建议使用 next-intlayer@>=7.x.x 来避免此限制。

配置 TypeScript

Intlayer 使用模块扩展（module augmentation）来利用 TypeScript 的优势并增强你的 codebase 的类型安全性。

自动完成

翻译错误

确保你的 TypeScript 配置包含自动生成的类型。

tsconfig.json

复制代码

复制代码到剪贴板

{  // ... 你现有的 TypeScript 配置  "include": [    // ... 你现有的 TypeScript 配置    ".intlayer/**/*.ts", // 包含自动生成的类型  ],}

{  // ... 你现有的 TypeScript 配置  "include": [    // ... 你现有的 TypeScript 配置    ".intlayer/**/*.ts", // 包含自动生成的类型  ],}

Git 配置

建议将 Intlayer 生成的文件忽略（ignore）。这样可以避免将这些文件提交到你的 Git 仓库。

为此，你可以将以下内容添加到你的 .gitignore 文件中：

.gitignore

复制代码

复制代码到剪贴板

# 忽略 Intlayer 生成的文件.intlayer

# 忽略 Intlayer 生成的文件.intlayer

VS Code Extension

为了提升在 Intlayer 的开发体验，你可以安装官方的 Intlayer VS Code Extension。

从 VS Code Marketplace 安装

此扩展提供：

Autocompletion：翻译键自动补全。
Real-time error detection：实时检测缺失的翻译。
内联预览 翻译后的内容。
快速操作 以便轻松创建和更新翻译。

有关如何使用该扩展的更多详细信息，请参阅 Intlayer VS Code 扩展文档。

更进一步

要深入了解，您可以实现可视化编辑器或使用 CMS 将内容外部化。

Next.js 15

Next.js和页面路由器

版本历史

使用 Intlayer 翻译你的 Next.js 16 网站（页面路径中不包含 [locale]） | 国际化 (i18n)

目录

为什么选择 Inlayer 而不是替代品？

在 Next.js 应用中设置 Intlayer 的逐步指南

第一步：安装依赖

配置您的项目

声明您的内容

在代码中使用内容

配置 Proxy 以进行 locale 检测

更改您内容的语言

（可选）步骤 9：在 Server Actions 中获取当前 locale

优化你的 bundle 大小

第 3 步：在 Next.js 配置中集成 Intlayer

第4步：定义动态 locale 路由

在 Turbopack 上监视字典更改

配置 TypeScript

Git 配置

VS Code Extension

更进一步