作者:
    Creation:2024-12-07Last update:2026-06-23

    使用Intlayer翻译您的Next.js and Page Router | 国际化(i18n)

    ide.intlayer.org

    目录

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

    与“next-intl”或“i18next”等主要解决方案相比，Intlayer是一个具有集成优化的解决方案，例如：

    Intlayer 经过优化，可以与 服务器组件 配合使用，以实现高效渲染，并且与 Turbopack 完全兼容。它不会阻止静态渲染，并提供中间件以及扩展国际化 (i18n) 所需的所有功能。

    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 来帮助您管理多语言内容实时，与译员、文案人员和其他团队成员无缝协作。内容可以本地和/或远程存储。

    使用 Page Router 在 Next.js 应用中设置 Intlayer 的分步指南

    1. 安装依赖

      使用您喜欢的包管理器安装必要的包：

      bash
      npx intlayer@canary init --interactive    # v9# npx intlayer init                       # v8
      --interactive 标志是可选的。如果您是 AI 代理，请使用 intlayer-cli init。
      该命令将检测您的环境并安装所需的软件包。例如：
      bash
      npm install intlayer next-intlayer
      • intlayer

      核心包，提供用于配置管理、翻译、内容声明、转译和命令行工具的国际化工具。

      • next-intlayer

        将 Intlayer 与 Next.js 集成的包。它提供了 Next.js 国际化的上下文提供者和钩子。此外，还包含用于将 Intlayer 集成到 Webpack 或 Turbopack 的 Next.js 插件，以及用于检测用户首选语言环境、管理 Cookie 和处理 URL 重定向的中间件。

    2. 配置您的项目

      创建一个配置文件以定义您的应用程序支持的语言：

      intlayer.config.ts
      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. 将 Intlayer 集成到 Next.js 配置中

      修改您的 Next.js 配置以集成 Intlayer：

      next.config.mjs
      import { withIntlayer } from "next-intlayer/server";/** @type {import('next').NextConfig} */const nextConfig = {  // 您现有的 Next.js 配置};export default withIntlayer(nextConfig);
      withIntlayer() Next.js 插件用于将 Intlayer 集成到 Next.js 中。它确保内容声明文件的构建，并在开发模式下监视这些文件。它在 Webpack 或 Turbopack 环境中定义 Intlayer 环境变量。此外，它提供别名以优化性能，并确保与服务器组件的兼容性。

    4. 配置中间件以检测语言环境

      设置中间件以自动检测并处理用户的首选语言环境：

      src/middleware.ts
      export { intlayerProxy as middleware } from "next-intlayer/middleware";

export const config = {
  matcher:
    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
};
      调整 matcher 参数以匹配您的应用程序路由。更多详情，请参阅 Next.js 关于配置 matcher 的文档。

    5. 定义动态本地化路由

      实现动态路由，根据用户的语言环境提供本地化内容。

      1. 创建特定语言环境的页面：

        重命名您的主页面文件，包含 [locale] 动态段。

        bash
        mv src/pages/index.tsx src/pages/[locale]/index.tsx

      2. 更新 _app.tsx 以处理本地化：

        plaintext
        修改您的 `_app.tsx`，添加 Intlayer 提供者。```tsx fileName="src/pages/_app.tsx" codeFormat="typescript"import type { FC } from "react";import type { AppProps } from "next/app";import { IntlayerClientProvider } from "next-intlayer";const App = FC<AppProps>({ Component, pageProps }) => {  const { locale } = pageProps;  return (    <IntlayerClientProvider locale={locale}>      <Component {...pageProps} />    </IntlayerClientProvider>  );}export default MyApp;``````jsx fileName="src/pages/_app.mjx" codeFormat="esm"import { IntlayerClientProvider } from "next-intlayer";const App = ({ Component, pageProps }) => (  <IntlayerClientProvider locale={locale}>    <Component {...pageProps} />  </IntlayerClientProvider>);export default App;``````jsx fileName="src/pages/_app.csx" codeFormat="commonjs"

        const { IntlayerClientProvider } = require("next-intlayer");

      const App = ({ Component, pageProps }) => ( );

      module.exports = App;

      plaintext
      3.  **设置 `getStaticPaths` 和 `getStaticProps`:**在你的 `[locale]/index.tsx` 文件中，定义路径和属性以处理不同的语言环境。````tsx fileName="src/pages/[locale]/index.tsx" codeFormat="typescript"import type { FC } from "react";import type { GetStaticPaths, GetStaticProps } from "next";import { type Locales, getConfiguration } from "intlayer";const HomePage: FC = () => <div>{/* 你的内容写在这里 */}</div>;export const getStaticPaths: GetStaticPaths = () => {      const { internationalization } = getConfiguration();      const { locales } = internationalization;      const paths = locales.map((locale) => ({        params: { locale },      }));      return { paths, fallback: false };    };    export const getStaticProps: GetStaticProps = ({ params }) => {      const locale = params?.locale as string;      return {        props: {          locale,        },      };    };    export default HomePage;    ```    ```jsx fileName="src/pages/[locale]/index.mjx" codeFormat="esm"    import { getConfiguration } from "intlayer";    import { ComponentExample } from "@components/ComponentExample";    const HomePage = () => <div>{/* 你的内容写在这里 */}</div>;    export const getStaticPaths = () => {      const { internationalization } = getConfiguration();      const { locales } = internationalization;      const paths = locales.map((locale) => ({        params: { locale },      }));      return { paths, fallback: false };    };    export const getStaticProps = ({ params }) => {      const locale = params?.locale;      return {        props: {          locale,        },      };    };    ```    ```jsx fileName="src/pages/[locale]/index.csx" codeFormat="commonjs"    const { getConfiguration } = require("intlayer");    const { ComponentExample } = require("@components/ComponentExample");    const HomePage = () => <div>{/* 你的内容写在这里 */}</div>;    const getStaticPaths = async () => {      const { internationalization } = getConfiguration();      const { locales } = internationalization;      const paths = locales.map((locale) => ({        params: { locale },      }));      return { paths, fallback: false };    };    const getStaticProps = async ({ params }) => {      const locale = params?.locale;      return {        props: {          locale,        },      };    };    module.exports = {      getStaticProps,      getStaticPaths,      default: HomePage,    };    ```> `getStaticPaths` 和 `getStaticProps` 确保您的应用程序在 Next.js 页面路由中预构建所有本地化所需的页面。此方法减少了运行时计算，从而提升用户体验。更多详情，请参阅 Next.js 文档中的 [`getStaticPaths`](https://nextjs.org/docs/pages/building-your-application/data-fetching/get-static-paths) 和 [`getStaticProps`](https://nextjs.org/docs/pages/building-your-application/data-fetching/get-static-props)。

    6. 声明您的内容

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

      src/pages/[locale]/home.content.ts
      import { t, type Dictionary } from "intlayer";

const homeContent = {
  key: "home",
  content: {
    title: t({
      en: "欢迎访问我的网站",
      fr: "Bienvenue sur mon site Web",
      es: "Bienvenido a mi sitio web",
    }),
    description: t({
      en: "通过编辑此页面开始。",
      fr: "Commencez par éditer cette page.",
      es: "Comience por editar esta página.",
    }),
  },
} satisfies Dictionary;

export default homeContent;

      ``

      有关声明内容的更多信息，请参阅内容声明指南。

    7. 在代码中使用内容

      在整个应用程序中访问您的内容字典以显示翻译内容。

      src/pages/[locale]/index.tsx
      import type { FC } from "react";
import { useIntlayer } from "next-intlayer";
import { ComponentExample } from "@components/ComponentExample";

const HomePage: FC = () => {
  const content = useIntlayer("home");

  return (
    <div>
      <h1>{content.title}</h1>
      <p>{content.description}</p>
      <ComponentExample />
      {/* 其他组件 */}
    </div>
  );
};

// ... 其余代码，包括 getStaticPaths 和 getStaticProps

export default HomePage;
      当在 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)}" />
      要了解有关 useIntlayer 钩子的更多信息，请参阅文档。

      1. 元数据的国际化

        如果您想要国际化您的元数据，例如页面标题，可以使用 Next.js 页面路由器提供的 getStaticProps 函数。在该函数内部，您可以通过 getIntlayer 函数获取内容以翻译您的元数据。

        src/pages/[locale]/metadata.content.ts
        import { type Dictionary, t } from "intlayer";
import { type Metadata } from "next";

const metadataContent = {
  key: "page-metadata",
  content: {
    title: t({
      en: "Create Next App",
      fr: "Créer une application Next.js",
      es: "Crear una aplicación Next.js",
    }),
    description: t({
      en: "Generated by create next app",
      fr: "Généré par create next app",
      es: "Generado por create next app",
    }),
  },
} satisfies Dictionary<Metadata>;

export default metadataContent;
        src/pages/[locale]/index.tsx
        import { GetStaticPaths, GetStaticProps } from "next";
import { getIntlayer, getMultilingualUrls } from "intlayer";
import { useIntlayer } from "next-intlayer";
import Head from "next/head";
import type { FC } from "react";

interface HomePageProps {
  locale: string;
  metadata: {
    title: string;
    description: string;
  };
  multilingualUrls: Record<string, string>;
}

const HomePage: FC<HomePageProps> = ({
  metadata,
  multilingualUrls,
  locale,
}) => {
  const content = useIntlayer("page");

  return (
    <div>
      <Head>
        <title>{metadata.title}</title>
        <meta name="description" content={metadata.description} />
        {/* 为SEO生成hreflang标签 */}
        {Object.entries(multilingualUrls).map(([lang, url]) => (
          <link key={lang} rel="alternate" hrefLang={lang} href={url} />
        ))}
        <link rel="canonical" href={multilingualUrls[locale]} />
      </Head>

      {/* 页面内容 */}
      <main>{/* 这里是您的页面内容 */}</main>
    </div>
  );
};

export const getStaticProps: GetStaticProps<HomePageProps> = async ({
  params,
}) => {
  const locale = params?.locale as string;

  const metadata = getIntlayer("page-metadata", locale);

  /**
   * 生成一个包含每个语言环境对应 URL 的对象。
   *
   * 示例：
   * ```ts
   *  getMultilingualUrls('/about');
   *
   *  // 返回
   *  // {
   *  //   en: '/about',
   *  //   fr: '/fr/about',
   *  //   es: '/es/about',
   *  // }
   * ```
   */
  const multilingualUrls = getMultilingualUrls("/");

  return {
    props: {
      locale,
      metadata,
      multilingualUrls,
    },
  };
};

export default HomePage;

// ... 其余代码包括 getStaticPaths
        请注意，从 next-intlayer 导入的 getIntlayer 函数会将您的内容包装在一个 IntlayerNode 中，从而允许与可视化编辑器集成。相比之下，从 intlayer 导入的 getIntlayer 函数则直接返回您的内容，不带额外属性。

        或者，您可以使用 getTranslation 函数来声明您的元数据。然而，推荐使用内容声明文件，以便自动化您的元数据翻译，并在某个阶段将内容外置。

        src/pages/[locale]/index.tsx
        import { GetStaticPaths, GetStaticProps } from "next";
import {
  type IConfigLocales,
  getTranslation,
  getMultilingualUrls,
} from "intlayer";
import { useIntlayer } from "next-intlayer";
import Head from "next/head";
import type { FC } from "react";

interface HomePageProps {
  locale: string;
  metadata: {
    title: string;
    description: string;
  };
  multilingualUrls: Record<string, string>;
}

const HomePage: FC<HomePageProps> = ({ metadata, multilingualUrls, locale }) => {
  const content = useIntlayer("page");

  return (
    <div>
      <Head>
        <title>{metadata.title}</title>
        <meta name="description" content={metadata.description} />
        {/* 生成用于SEO的hreflang标签 */}
        {Object.entries(multilingualUrls).map(([lang, url]) => (
          <link
            key={lang}
            rel="alternate"
            hrefLang={lang}
            href={url}
          />
        ))}
        <link rel="canonical" href={multilingualUrls[locale]} />
      </Head>

      {/* 页面内容 */}
      <main>
        {/* 你的页面内容放这里 */}
      </main>
    </div>
  );
};

export const getStaticProps: GetStaticProps<HomePageProps> = async ({
  params
}) => {
  const locale = params?.locale as string;
  const t = <T>(content: IConfigLocales<T>) => getTranslation(content, locale);

  const metadata = {
    title: t<string>({
      en: "My title",
      fr: "Mon titre",
      es: "Mi título",
    }),
    description: t({
      en: "My description",
      fr: "Ma description",
      es: "Mi descripción",
    }),
  };

  const multilingualUrls = getMultilingualUrls("/");

  return {
    props: {
      locale,
      metadata,
      multilingualUrls,
    },
  };
};

export default HomePage;

// ... 包括 getStaticPaths 的其余代码
        了解有关元数据优化的更多信息，请参阅官方 Next.js 文档。

      2. 更改内容语言

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

        src/components/LanguageSwitcher.tsx
        import {
  Locales,
  getHTMLTextDir,
  getLocaleName,
  getLocalizedUrl,
} from "intlayer";
import { useLocalePageRouter } from "next-intlayer";
import { type FC } from "react";
import Link from "next/link";

const LocaleSwitcher: FC = () => {
  const { locale, pathWithoutLocale, availableLocales } = useLocalePageRouter();

  return (
    <div>
      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
      <div id="localePopover" popover="auto">
        {availableLocales.map((localeItem) => (
          <Link
            href={getLocalizedUrl(pathWithoutLocale, localeItem)}
            hrefLang={localeItem}
            key={localeItem}
            aria-current={locale === localeItem ? "page" : undefined}
            onClick={() => setLocale(localeItem)}
          >
            <span>
              {/* 语言环境 - 例如 FR */}
              {localeItem}
            </span>
            <span>
              {/* 该语言环境中的语言名称 - 例如 Français */}
              {getLocaleName(localeItem, locale)}
            </span>
            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
              {/* 当前语言环境中的语言 - 例如当前语言环境设置为 Locales.SPANISH 时显示 Francés */}
              {getLocaleName(localeItem)}
            </span>
            <span dir="ltr" lang={Locales.ENGLISH}>
              {/* 英语中的语言 - 例如 French */}
              {getLocaleName(localeItem, Locales.ENGLISH)}
            </span>
          </Link>
        ))}
      </div>
    </div>
  );
};
        另一种方式是使用 useLocale 钩子提供的 setLocale 函数。该函数不会预取页面，并且会重新加载页面。
        在这种情况下，如果不使用 router.push 进行重定向，只有您的服务器端代码会更改内容的语言环境。
        src/components/LocaleSwitcher.tsx
        "use client";import { useRouter } from "next/navigation";import { useLocale } from "next-intlayer";import { getLocalizedUrl } from "intlayer";// ... 其余代码const router = useRouter();const { setLocale } = useLocale({  onLocaleChange: (locale) => {    router.push(getLocalizedUrl(pathWithoutLocale, locale));  },});return <button onClick={() => setLocale(Locales.FRENCH)}>切换到法语</button>;
        useLocalePageRouter API 与 useLocale 相同。要了解更多关于 useLocale 钩子的内容，请参阅文档。

        文档参考：

      3. 创建本地化链接组件

        为了确保您的应用导航遵循当前的语言环境，您可以创建一个自定义的 Link 组件。该组件会自动在内部 URL 前添加当前语言的前缀。例如，当讲法语的用户点击“关于”页面的链接时，他们会被重定向到 /fr/about，而不是 /about。

        这种行为有多个好处：

        • SEO 和用户体验：本地化的 URL 有助于搜索引擎正确索引特定语言的页面，并为用户提供其偏好的语言内容。
        • 一致性：通过在整个应用中使用本地化链接，确保导航保持在当前语言环境内，避免意外的语言切换。
        • 可维护性：将本地化逻辑集中在单个组件中，简化了 URL 的管理，使代码库更易于维护和扩展，随着应用的增长更加高效。

        下面是使用 TypeScript 实现的本地化 Link 组件示例：

        src/components/Link.tsx
        "use client";

import { getLocalizedUrl } from "intlayer";
import NextLink, { type LinkProps as NextLinkProps } from "next/link";
import { useLocale } from "next-intlayer";
import { forwardRef, PropsWithChildren, type ForwardedRef } from "react";

/**
 * 工具函数，用于检查给定的 URL 是否为外部链接。
 * 如果 URL 以 http:// 或 https:// 开头，则视为外部链接。
 */
export const checkIsExternalLink = (href?: string): boolean =>
  /^https?:\/\//.test(href ?? "");

/**
 * 自定义 Link 组件，根据当前语言环境调整 href 属性。
 * 对于内部链接，使用 `getLocalizedUrl` 在 URL 前添加语言前缀（例如 /fr/about）。
 * 这确保导航保持在相同的语言环境上下文中。
 */
export const Link = forwardRef<
  HTMLAnchorElement,
  PropsWithChildren<NextLinkProps>
>(({ href, children, ...props }, ref: ForwardedRef<HTMLAnchorElement>) => {
  const { locale } = useLocale();
  const isExternalLink = checkIsExternalLink(href.toString());

  // 如果链接是内部链接且提供了有效的 href，则获取本地化的 URL。
  const hrefI18n: NextLinkProps["href"] =
    href && !isExternalLink ? getLocalizedUrl(href.toString(), locale) : href;

  return (
    <NextLink href={hrefI18n} ref={ref} {...props}>
      {children}
    </NextLink>
  );
});

Link.displayName = "Link";

        工作原理

        • 检测外部链接：
          辅助函数 checkIsExternalLink 用于判断 URL 是否为外部链接。外部链接保持不变，因为它们不需要本地化。

        • 获取当前语言环境：
          useLocale 钩子提供当前的语言环境（例如，fr 表示法语）。

        • 本地化 URL：
          对于内部链接（即非外部链接），使用 getLocalizedUrl 自动为 URL 添加当前语言环境的前缀。这意味着如果用户的语言环境是法语，传入的 /about 会被转换为 /fr/about。

        • 返回链接：
          该组件返回一个带有本地化 URL 的 <a> 元素，确保导航与语言环境保持一致。

        通过在整个应用中集成此 Link 组件，您可以保持一致且具备语言感知的用户体验，同时提升 SEO 和可用性。

      4. 优化您的Bundle 大小

        使用 next-intlayer 时，字典默认会包含在每个页面的打包文件中。为了优化打包体积，Intlayer 提供了一个可选的 SWC 插件，该插件通过宏智能替换 useIntlayer 调用。这确保字典只会包含在实际使用它们的页面的打包文件中。

        要启用此优化，请安装 @intlayer/swc 包。安装后，next-intlayer 会自动检测并使用该插件：

        bash
        npm install @intlayer/swc --save-dev
        注意：此优化仅适用于 Next.js 13 及以上版本。

        注意：该包默认未安装，因为 SWC 插件在 Next.js 中仍处于实验阶段，未来可能会有所变化。

        5. </Steps>

        配置 TypeScript

        Intlayer 使用模块增强（module augmentation）来利用 TypeScript 的优势，使您的代码库更健壮。

        Autocompletion

        Translation error

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

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

        Git 配置

        为了保持您的代码库整洁并避免提交生成的文件，建议忽略由 Intlayer 创建的文件。

        将以下内容添加到您的 .gitignore 文件中：

        .gitignore
        # 忽略 Intlayer 生成的文件.intlayer

        VS Code 扩展

        为了提升您使用 Intlayer 的开发体验，您可以安装官方的 Intlayer VS Code 扩展。

        从 VS Code 市场安装

        该扩展提供：

        • 翻译键的自动补全。
        • 缺失翻译的实时错误检测。
        • 翻译内容的内联预览。
        • 轻松创建和更新翻译的快速操作。

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

        其他资源

        通过遵循本指南，您可以将 Intlayer 有效集成到使用页面路由的 Next.js 应用程序中，为您的 Web 项目提供强大且可扩展的国际化支持。

        深入了解

        要进一步扩展，您可以实现可视化编辑器或使用内容管理系统（CMS）将内容外部化。

        Next.js 无 locale URL
        编译器