作者:
    Aymeric PINEAU
    Creation:2025-09-09Last update:2026-08-25

    使用Intlayer翻译您的Tanstack Start | 国际化(i18n)

    目录

    本指南演示如何在 Tanstack Start 项目中集成 Intlayer，实现无缝国际化，支持基于区域设置的路由、TypeScript 支持以及现代开发实践。

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

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

    完整的 TanStack Start 覆盖

    Intlayer 针对 TanStack Start 进行了全面优化，提供多语言路由、cookie 管理、站点地图生成、动态内容加载以及扩展国际化 (i18n) 工作所需的所有功能。

    </Accordion>

    捆绑尺寸

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

    </Accordion>

    可维护性

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

    人工智能代理

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

    自动化

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

    </Accordion>

    表现

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

    无需开发即可扩展

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

    在 Tanstack Start 应用程序中设置 Intlayer 的分步指南

    www.youtube.com
    ide.intlayer.org
    intlayer-tanstack-start-template.vercel.app

    在 GitHub 上查看 应用程序模板。

    1. 创建项目

      首先，按照 TanStack Start 网站上的 开始新项目 指南创建一个新的 TanStack Start 项目。

    2. 安装 Intlayer 包

      使用您首选的包管理器安装必要的包：

      bash
      npx intlayer init --interactive
      --interactive 标志是可选的。如果您是 AI 代理，请使用 intlayer-cli init。
      此命令将检测您的环境并安装所需的包。例如：
      bash
      npm install intlayer react-intlayer
npm install vite-intlayer --save-dev

      • intlayer

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

      • react-intlayer 将 Intlayer 与 React 应用程序集成的包。为 React 国际化提供上下文提供程序和 hooks。

      • vite-intlayer 包含用于将 Intlayer 与 Vite bundler 集成的 Vite 插件，以及用于检测用户首选语言、管理 cookies 和处理 URL 重定向的 middleware。

    3. 配置您的项目

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

      intlayer.config.ts
      import type { IntlayerConfig } from "intlayer";

import { Locales } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    defaultLocale: Locales.ENGLISH,
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
  },
};

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

    4. 在 Vite 配置中集成 Intlayer

      将 intlayer 插件添加到您的配置中：

      vite.config.ts
      import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";
import { nitro } from "nitro/vite";
import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

const config = defineConfig({
  plugins: [
    nitro(),
    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
    tanstackStart({
      router: {
        routeFileIgnorePattern:
          ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5|md|mdx|yaml|yml)$",
      },
    }),
    viteReact(),
  ],
});

export default config;
      intlayer() Vite 插件用于将 Intlayer 与 Vite 集成。它确保构建内容声明文件并在开发模式下监视它们。它在 Vite 应用程序中定义 Intlayer 环境变量。此外，它提供别名来优化性能。

    5. 创建根布局

      配置您的根布局以支持国际化，使用 useParams 检测当前语言，并在 html 标签上设置 lang 和 dir 属性。

      src/routes/__root.tsx
      import {
  createRootRouteWithContext,
  getRouteApi,
  HeadContent,
  Scripts,
} from "@tanstack/react-router";
import { defaultLocale, getHTMLTextDir } from "intlayer";
import { type ReactNode } from "react";
import { IntlayerProvider } from "react-intlayer";

const localeRoute = getRouteApi("/{-$locale}");

export const Route = createRootRouteWithContext<{}>()({
  head: () => ({
    meta: [
      {
        charSet: "utf-8",
      },
      {
        content: "width=device-width, initial-scale=1",
        name: "viewport",
      },
      {
        title: "TanStack Start Starter",
      },
    ],
  }),

  shellComponent: RootDocument,
});

function RootDocument({ children }: { children: ReactNode }) {
  const params = localeRoute.useParams();
  const locale = params?.locale ?? defaultLocale;

  return (
    <html dir={getHTMLTextDir(locale)} lang={locale}>
      <head>
        <HeadContent />
      </head>
      <body>
        <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
        <Scripts />
      </body>
    </html>
  );
}

    6. 创建语言布局

      创建一个处理语言前缀并执行验证的布局。

      src/routes/{-$locale}/route.tsx
      import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";
import { validatePrefix } from "intlayer";

export const Route = createFileRoute("/{-$locale}")({
  beforeLoad: ({ params }) => {
    const localeParam = params.locale;

    // 验证语言前缀
    const { isValid, localePrefix } = validatePrefix(localeParam);

    if (!isValid) {
      throw redirect({
        to: "/{-$locale}/404",
        params: { locale: localePrefix },
      });
    }
  },
  component: Outlet,
});
      在这里，{-$locale} 是一个动态路由参数，被替换为当前语言。这种符号使该插槽可选，允许它与路由模式（如 'prefix-no-default' 等）一起工作。

      请注意，如果您在同一路由中使用多个动态段（例如 /{-$locale}/other-path/$anotherDynamicPath/...），此插槽可能会导致问题。 对于 'prefix-all' 模式，您可能更喜欢将插槽切换为 $locale。 对于 'no-prefix' 或 'search-params' 模式，您可以完全移除该插槽。

    7. 声明您的内容

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

      src/contents/page.content.ts
      import type { Dictionary } from "intlayer";

import { t } from "intlayer";

const appContent = {
  content: {
    links: {
      about: t({
        zh: "关于",
        en: "About",
        es: "Acerca de",
        fr: "À propos",
      }),
      home: t({
        zh: "首页",
        en: "Home",
        es: "Inicio",
        fr: "Accueil",
      }),
    },
    meta: {
      title: t({
        zh: "欢迎使用 Intlayer + TanStack Router",
        en: "Welcome to Intlayer + TanStack Router",
        es: "Bienvenido a Intlayer + TanStack Router",
        fr: "Bienvenue à Intlayer + TanStack Router",
      }),
      description: t({
        zh: "这是使用 Intlayer 与 TanStack Router 的示例",
        en: "This is an example of using Intlayer with TanStack Router",
        es: "Este es un ejemplo de uso de Intlayer con TanStack Router",
        fr: "Ceci est un exemple d'utilisation d'Intlayer avec TanStack Router",
      }),
    },
  },
  key: "app",
} satisfies Dictionary;

export default appContent;
      您的内容声明可以在应用程序中的任何位置定义，只要它们包含在 contentDir 目录中（默认为 ./app）。并匹配内容声明文件扩展名（默认为 .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}）。
      有关更多详情，请参考 内容声明文档。

    8. 创建语言感知组件和 Hooks

      为语言感知导航创建一个 LocalizedLink 组件：

      src/components/localized-link.tsx
      import type { FC } from "react";

import { Link, type LinkComponentProps } from "@tanstack/react-router";
import { useLocale } from "react-intlayer";
import { getPrefix } from "intlayer";

export const LOCALE_ROUTE = "{-$locale}" as const;

export type To = StripLocalePrefix<LinkComponentProps["to"]>;

export type StripLocalePrefix<T extends string | undefined> = T extends
  `/${typeof LOCALE_ROUTE}/` | `/${typeof LOCALE_ROUTE}`
  ? "/"
  : T extends `/${typeof LOCALE_ROUTE}/${infer Rest}`
    ? `/${Rest}`
    : T;

type LocalizedLinkProps = {
  to?: To;
} & Omit<LinkComponentProps, "to">;

export const LocalizedLink: FC<LocalizedLinkProps> = (props) => {
  const { locale } = useLocale();
  const { localePrefix } = getPrefix(locale);

  return (
    <Link
      {...props}
      params={{
        locale: localePrefix,
        ...(typeof props?.params === "object" ? props?.params : {}),
      }}
      to={`/${LOCALE_ROUTE}${props.to}` as LinkComponentProps["to"]}
    />
  );
};

      此组件有两个目标：

      • 从 URL 中删除不必要的 {-$locale} 前缀。
      • 将语言参数注入到 URL 中，以确保用户直接重定向到本地化路由。

      然后我们可以创建一个 useLocalizedNavigate hook 来进行编程导航：

      src/hooks/useLocalizedNavigate.tsx
      import { useNavigate } from "@tanstack/react-router";
import { getPrefix } from "intlayer";
import { useLocale } from "react-intlayer";
import type { StripLocalePrefix } from "@/components/localized-link";
import type { FileRouteTypes } from "@/routeTree.gen";

type NavigateFn = ReturnType<typeof useNavigate>;
type BaseNavigateOptions = Parameters<NavigateFn>[0];

type LocalizedTo = StripLocalePrefix<FileRouteTypes["to"]>;

export type LocalizedNavigateOptions = Omit<
  BaseNavigateOptions,
  "to" | "params"
> & {
  to: LocalizedTo;
  params?: Omit<NonNullable<BaseNavigateOptions["params"]>, "locale">;
};

type LocalizedNavigate = (
  options: LocalizedNavigateOptions
) => ReturnType<NavigateFn>;

export const useLocalizedNavigate = () => {
  const navigate = useNavigate();

  const { locale } = useLocale();

  const localizedNavigate: LocalizedNavigate = (args: any) => {
    const { localePrefix } = getPrefix(locale);

    if (typeof args === "string") {
      return navigate({
        to: `/${LOCALE_ROUTE}${args}`,
        params: { locale: localePrefix },
      });
    }

    const { to, ...rest } = args;

    const localizedTo = `/${LOCALE_ROUTE}${to}` as any;

    return navigate({
      to: localizedTo,
      params: { locale: localePrefix, ...rest } as any,
    });
  };

  return localizedNavigate;
};

    9. 在您的页面中使用 Intlayer

      在组件中请默认使用 useIntlayer：这是读取内容的推荐方式，编译器会把它解析为当前渲染的语言环境。仅在 React 树之外（路由 head、loader 和服务端函数）才使用 getIntlayer / getIntlayerAsync。

      在整个应用程序中访问您的内容字典：

      本地化主页

      src/routes/{-$locale}/index.tsx
      import { createFileRoute } from "@tanstack/react-router";
import { useIntlayer } from "react-intlayer";

import LocaleSwitcher from "@/components/locale-switcher";
import { LocalizedLink } from "@/components/localized-link";
import { useLocalizedNavigate } from "@/hooks/useLocalizedNavigate";

export const Route = createFileRoute("/{-$locale}/")({
  component: RouteComponent,
});

function RouteComponent() {
  const content = useIntlayer("app");
  const navigate = useLocalizedNavigate();

  return (
    <div>
      <div>
        {content.title}
        <LocaleSwitcher />
        <div>
          <LocalizedLink to="/">{content.links.home}</LocalizedLink>
          <LocalizedLink to="/about">{content.links.about}</LocalizedLink>
        </div>
        <div>
          <button onClick={() => navigate({ to: "/" })}>
            {content.links.home}
          </button>
          <button onClick={() => navigate({ to: "/about" })}>
            {content.links.about}
          </button>
        </div>
      </div>
    </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)}" />
      要了解更多关于 useIntlayer hook 的信息，请参考文档。

    10. 创建语言切换器组件

      创建一个组件来允许用户更改语言：

      src/components/locale-switcher.tsx
      import { useLocation } from "@tanstack/react-router";
import {
  getHTMLTextDir,
  getLocaleName,
  getPathWithoutLocale,
  getPrefix,
  Locales,
} from "intlayer";
import type { FC } from "react";
import { useLocale } from "react-intlayer";

import { LocalizedLink, type To } from "./localized-link";

export const LocaleSwitcher: FC = () => {
  const { pathname } = useLocation();

  const { availableLocales, locale, setLocale } = useLocale();

  const pathWithoutLocale = getPathWithoutLocale(pathname);

  return (
    <ol>
      {availableLocales.map((localeEl) => (
        <li key={localeEl}>
          <LocalizedLink
            aria-current={localeEl === locale ? "page" : undefined}
            onClick={() => setLocale(localeEl)}
            params={{ locale: getPrefix(localeEl).localePrefix }}
            to={pathWithoutLocale as To}
          >
            <span>
              {/* 区域设置 - 例如 FR */}
              {localeEl}
            </span>
            <span>
              {/* 用其自己的区域设置显示的语言 - 例如 Français */}
              {getLocaleName(localeEl, locale)}
            </span>
            <span dir={getHTMLTextDir(localeEl)} lang={localeEl}>
              {/* 用当前区域设置显示的语言 - 例如当前区域设置为 Locales.SPANISH 时的 Francés */}
              {getLocaleName(localeEl)}
            </span>
            <span dir="ltr" lang={Locales.ENGLISH}>
              {/* 用英文显示的语言 - 例如 French */}
              {getLocaleName(localeEl, Locales.ENGLISH)}
            </span>
          </LocalizedLink>
        </li>
      ))}
    </ol>
  );
};
      要了解更多关于 useLocale hook 的信息，请参考文档。

    11. HTML 属性管理

      如第 5 步所述，您可以在根组件中使用 useParams 来管理 html 标签的 lang 和 dir 属性。这确保在服务器和客户端上设置正确的属性。

      src/routes/__root.tsx
      const localeRoute = getRouteApi("/{-$locale}");

function RootDocument({ children }: { children: ReactNode }) {
  const params = localeRoute.useParams();
  const locale = params?.locale ?? defaultLocale;

  return (
    <html dir={getHTMLTextDir(locale)} lang={locale}>
      {/* ... */}
    </html>
  );
}

    12. 添加中间件

      您也可以使用 intlayerProxy 为您的应用程序添加服务器端路由。该插件将根据 URL 自动检测当前区域设置并设置适当的区域设置 cookie。如果未指定任何区域设置，该插件将根据用户的浏览器语言偏好确定最合适的区域设置。如果未检测到任何区域设置，它将重定向到默认区域设置。

      注意，要在生产环境中使用 intlayerProxy，您需要将 vite-intlayer 软件包从 devDependencies 切换到 dependencies。
      从 Intlayer v9 开始，intlayerProxy() 直接捆绑在 intlayer() 插件中，并通过 routing.enableProxy 选项（默认为 true）默认启用。如下所示分别注册它现在是可选的：为了向后兼容性和需要控制插件顺序的设置而保留。设置 routing.enableProxy: false 以选择退出。请参考 v9 发行说明。
      vite.config.ts
      import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";
import { nitro } from "nitro/vite";
import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

export default defineConfig({
  plugins: [
    nitro(),
    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
    tanstackStart({
      router: {
        routeFileIgnorePattern:
          ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5|md|mdx|yaml|yml)$",
      },
    }),
    viteReact(),
  ],
});

    13. 国际化您的元数据

      getIntlayer 针对合并的字典（包含每个声明的区域设置的字典）进行同步解析。head 保持同步，不会等待任何内容，但整个多语言字典被拉入发送到浏览器的路由块中。

      src/routes/{-$locale}/index.tsx
      import { createFileRoute } from "@tanstack/react-router";
import {
  defaultLocale,
  getIntlayer,
  getLocalizedUrl,
  localeMap,
} from "intlayer";

export const Route = createFileRoute("/{-$locale}/")({
  component: RouteComponent,
  head: ({ params }) => {
    const { locale = defaultLocale } = params;
    const path = "/"; // 此路由的路径

    const metaContent = getIntlayer("app", locale);

    return {
      links: [
        // 规范链接：指向当前本地化页面
        { rel: "canonical", href: getLocalizedUrl(path, locale) },

        // Hreflang：告诉 Google 所有本地化版本
        ...localeMap(({ locale: mapLocale }) => ({
          rel: "alternate",
          hrefLang: mapLocale,
          href: getLocalizedUrl(path, mapLocale),
        })),

        // x-default：适用于语言不匹配的用户
        // 定义默认的回退区域设置（通常是您的主要语言）
        {
          rel: "alternate",
          hrefLang: "x-default",
          href: getLocalizedUrl(path, defaultLocale),
        },
      ],
      meta: [
        { title: metaContent.title },
        { name: "description", content: metaContent.meta.description },
      ],
    };
  },
});

      最适合小型元数据字典、少数几个区域设置或原型设计时使用。

      getIntlayerAsync（从 v9.4 开始可用）的行为类似于 getIntlayer，但构建插件将其指向 .intlayer/dynamic_dictionaries/ 中的按区域设置块，而不是合并字典。因此，页面仅发送它呈现的区域设置。由于该块是按需加载的，head 变为 async：

      src/routes/{-$locale}/index.tsx
      import { createFileRoute } from "@tanstack/react-router";
import {
  defaultLocale,
  getIntlayerAsync,
  getLocalizedUrl,
  localeMap,
} from "intlayer";

export const Route = createFileRoute("/{-$locale}/")({
  component: RouteComponent,
  head: async ({ params }) => {
    const { locale = defaultLocale } = params;
    const path = "/"; // 此路由的路径

    const metaContent = await getIntlayerAsync("app", locale);

    return {
      links: [
        // 规范链接：指向当前本地化页面
        { rel: "canonical", href: getLocalizedUrl(path, locale) },

        // Hreflang：告诉 Google 所有本地化版本
        ...localeMap(({ locale: mapLocale }) => ({
          rel: "alternate",
          hrefLang: mapLocale,
          href: getLocalizedUrl(path, mapLocale),
        })),

        // x-default：适用于语言不匹配的用户
        // 定义默认的回退区域设置（通常是您的主要语言）
        {
          rel: "alternate",
          hrefLang: "x-default",
          href: getLocalizedUrl(path, defaultLocale),
        },
      ],
      meta: [
        { title: metaContent.title },
        { name: "description", content: metaContent.meta.description },
      ],
    };
  },
});
      如果 head 读取多个字典，请使用 Promise.all 解析它们：在自己的行上等待每个 getIntlayerAsync 会链接请求，而不是并行运行它们。

      权衡：动态导入在 head 运行时解析，在文档呈现的关键路径上。在冷路由上，这会将 head 延迟几毫秒，可能会略微降低 LCP。

      在路由 loader 中解析字典，然后在 head 中从 loaderData 读取。匹配路由的加载程序并行运行，staleTime: Infinity 告诉 TanStack Router 结果永不过期，因此按区域设置块被解析一次，随后从路由器缓存提供，使 head 保持同步。

      src/routes/{-$locale}/index.tsx
      import { createFileRoute } from "@tanstack/react-router";
import {
  defaultLocale,
  getIntlayerAsync,
  getLocalizedUrl,
  localeMap,
} from "intlayer";

export const Route = createFileRoute("/{-$locale}/")({
  component: RouteComponent,
  // 与其他匹配的路由并行解析，不在 head 关键路径上
  loader: async ({ params }) => {
    const { locale = defaultLocale } = params;

    return { metaContent: await getIntlayerAsync("app", locale) };
  },
  // 给定区域设置的字典永不改变：解析块一次
  staleTime: Infinity,
  head: ({ params, loaderData }) => {
    const { locale = defaultLocale } = params;
    const path = "/"; // 此路由的路径

    return {
      links: [
        // 规范链接：指向当前本地化页面
        { rel: "canonical", href: getLocalizedUrl(path, locale) },

        // Hreflang：告诉 Google 所有本地化版本
        ...localeMap(({ locale: mapLocale }) => ({
          rel: "alternate",
          hrefLang: mapLocale,
          href: getLocalizedUrl(path, mapLocale),
        })),

        // x-default：适用于语言不匹配的用户
        // 定义默认的回退区域设置（通常是您的主要语言）
        {
          rel: "alternate",
          hrefLang: "x-default",
          href: getLocalizedUrl(path, defaultLocale),
        },
      ],
      meta: [
        { title: loaderData?.metaContent.title },
        {
          name: "description",
          content: loaderData?.metaContent.meta.description,
        },
      ],
    };
  },
});
      head 可能在加载程序解决之前被调用，因此 loaderData 的类型可能为 undefined。保持可选链接，或返回回退标题。

      您保持按区域设置块而不在 head 关键路径上支付其成本。代价是开发者体验：内容必须通过 loaderData 从加载程序显式线程化到 head。

      我应该选择哪种解析方式？

      静态解析 动态解析 缓存动态解析
      API getIntlayer getIntlayerAsync (v9.4+) getIntlayerAsync in loader (v9.4+)
      head 签名 synchronous async synchronous, reads loaderData
      传送的语言版本 every declared locale requested locale only requested locale only
      客户端导航 nothing to resolve re-entered on every match served from the router cache
      开发者体验 simplest one await content threaded through loaderData

    14. 在服务器操作中检索语言

      您可能希望从服务器操作或 API 端点内访问当前语言。 您可以使用 intlayer 中的 getLocale 帮助器来实现此目的。

      以下是使用 TanStack Start 服务器函数的示例：

      src/routes/{-$locale}/index.tsx
      import { createServerFn } from "@tanstack/react-start";
import {
  getRequestHeader,
  getRequestHeaders,
} from "@tanstack/react-start/server";
import { getCookie, getIntlayer, getLocale } from "intlayer";

export const getLocaleServer = createServerFn().handler(async () => {
  const locale = await getLocale({
    // 从请求中获取 cookie (默认: 'INTLAYER_LOCALE')
    getCookie: (name) => {
      const cookieString = getRequestHeader("cookie");

      return getCookie(name, cookieString);
    },
    // 从请求中获取标头 (默认: 'x-intlayer-locale')
    // 使用 Accept-Language 协商的回退
    getHeader: (name) => getRequestHeader(name),
  });

  // 使用 getIntlayerAsync() 检索一些内容
  const content = getIntlayer("app", locale);

  return { locale, content };
});

    15. 管理未找到页面

      当用户访问不存在的页面时，您可以显示自定义的未找到页面，语言前缀可能会影响未找到页面的触发方式。

      本地化首页

      如果你想在 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 hook 的信息，请参考文档。
      16. src/components/locale-switcher.tsx
      import { useLocation } from "@tanstack/react-router";
import {
  getHTMLTextDir,
  getLocaleName,
  getPathWithoutLocale,
  getPrefix,
  Locales,
} from "intlayer";
import type { FC } from "react";
import { useLocale } from "react-intlayer";

import { LocalizedLink, type To } from "./localized-link";

export const LocaleSwitcher: FC = () => {
  const { pathname } = useLocation();

  const { availableLocales, locale, setLocale } = useLocale();

  const pathWithoutLocale = getPathWithoutLocale(pathname);

  return (
    <ol>
      {availableLocales.map((localeEl) => (
        <li key={localeEl}>
          <LocalizedLink
            aria-current={localeEl === locale ? "page" : undefined}
            onClick={() => setLocale(localeEl)}
            params={{ locale: getPrefix(localeEl).localePrefix }}
            to={pathWithoutLocale as To}
          >
            <span>
              {/* 区域设置 - 例如 FR */}
              {localeEl}
            </span>
            <span>
              {/* 该语言用其自身区域设置表示 - 例如 Français */}
              {getLocaleName(localeEl, locale)}
            </span>
            <span dir={getHTMLTextDir(localeEl)} lang={localeEl}>
              {/* 该语言用当前区域设置表示 - 例如当前区域设置为 Locales.SPANISH 时的 Francés */}
              {getLocaleName(localeEl)}
            </span>
            <span dir="ltr" lang={Locales.ENGLISH}>
              {/* 该语言用英文表示 - 例如 French */}
              {getLocaleName(localeEl, Locales.ENGLISH)}
            </span>
          </LocalizedLink>
        </li>
      ))}
    </ol>
  );
};
      要了解更多关于 useLocale hook 的信息，请参考文档。

      </Step>

    16. HTML 属性管理

      return ( {/* ... _/} ); } {/_ ... */} </html> ); }

      export const Route = createFileRoute("/{-$locale}/")({ component: RouteComponent, head: async ({ params }) => { const { locale = defaultLocale } = params; const path = "/"; // The path for this route

      plaintext
      const metaContent = await getIntlayerAsync("app", locale);
      plaintext
      
> `head` 可能在 loader 完成之前被调用，因此 `loaderData` 的类型可能为 `undefined`。请保留可选链，或返回一个兜底标题。

你保留了按语言环境拆分的分块，却无需在 `head` 的关键路径上付出代价。代价在于开发体验：内容必须通过 `loaderData` 从 loader 显式传递到 `head`。

</Tab>

</Tabs>

### 该选择哪种解析方式？

|                | 静态解析             | 动态解析                    | 带缓存的动态解析                          |
| -------------- | -------------------- | --------------------------- | ----------------------------------------- |
| API            | `getIntlayer`        | `getIntlayerAsync`（v9.4+） | `loader` 中的 `getIntlayerAsync`（v9.4+） |
| `head` 签名    | 同步                 | `async`                     | 同步，读取 `loaderData`                   |
| 发送的语言环境 | 所有已声明的语言环境 | 仅请求的语言环境            | 仅请求的语言环境                          |
| 客户端导航     | 无需解析             | 每次匹配都重新执行          | 由路由缓存提供                            |
| 开发体验       | 最简单               | 一个 `await`                | 内容经由 `loaderData` 传递                |

---

    17. 在服务器操作中检索区域设置

      你可能想要从服务器操作或 API 端点内访问当前的区域设置。 你可以使用来自 intlayer 的 getLocale helper。

      以下是使用 TanStack Start 的服务器函数的示例：

      src/routes/{-$locale}/index.tsx
            return getCookie(name, cookieString);
    },
    // 从请求中获取 header（默认：'x-intlayer-locale'）
    // 使用 Accept-Language 协商进行回退
    getHeader: (name) => getRequestHeader(name),
  });

  // 使用 getIntlayer() 检索一些内容
  const content = getIntlayer("app", locale);

      `

    18. 管理未找到页面

      当用户访问不存在的页面时，你可以显示自定义的未找到页面，语言区域前缀可能会影响未找到页面的触发方式。

      理解 TanStack Router 的 404 处理与 Locale 前缀

      在 TanStack Router 中，处理带本地化路由的 404 页面需要采用多层方法：

      1. 专用 404 路由：用于显示 404 UI 的特定路由
      2. 路由级验证：验证 locale 前缀并将无效的前缀重定向到 404
      3. 捕获所有路由：捕获 locale 段内任何不匹配的路径
      src/routes/{-$locale}/404.tsx
      src/routes/{-$locale}/route.tsx
      src/routes/{-$locale}/$.tsx

    19. 提取组件内容

      可选

      20. 如果你有现有的 codebase，转换数千个文件可能会很耗时。

      为了简化此过程，Intlayer 提供了一个 compiler / extractor 来转换你的组件并提取内容。

      要设置它，你可以在 intlayer.config.ts 文件中添加 compiler 部分：

      intlayer.config.ts
      import { type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... 配置的其余部分
  compiler: {
    /**
     * 表示编译器是否应启用。
     */
    enabled: true,

    /**
     * 定义输出文件路径
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * 表示转换后是否应保存组件。
     *
     * - 如果为 `true`，编译器将在磁盘中重写组件文件。因此转换将是永久的，编译器将在下一个过程中跳过转换。这样，编译器可以转换应用程序，然后可以将其删除。
     *
     * - 如果为 `false`，编译器将仅在构建输出中注入 `useIntlayer()` 函数调用，并保持 base codebase 完整。转换将仅在内存中完成。
     */
    saveComponents: false,

      运行提取器以转换组件并提取内容

      bash

      bun x intlayer extract import { defineConfig } from "vite"; import { intlayer, intlayerCompiler } from "vite-intlayer";

      export default defineConfig({ plugins: [

      plaintext
      intlayer(),
intlayerCompiler(), // 添加编译器插件

      ], });

      plaintext

      bash packageManager="npm" npm run build # 或 npm run dev

      plaintext

      bash packageManager="pnpm" pnpm run build # 或 pnpm run dev

      plaintext

      bash packageManager="yarn" yarn build # 或 yarn dev

      plaintext

      bash packageManager="bun"

      • BLOCK 2 of 3（英文参考）：为空
      • BLOCK 2 of 3（中文待审核）：为空

      请提供：

      1. 英文源文件内容（需要审核的参考版本）
      2. 中文现有翻译内容（需要更新/修正的版本）

      bun run build # 或 bun run dev import { localeFlatMap } from "intlayer"; // ... 其他导入

      export default defineConfig({ plugins: [

      plaintext
      // ... 其他插件
tanstackStart({
  // ... 其他配置
  sitemap: {
    enabled: false,
  },
  prerender: {
    enabled: true,
    crawlLinks: false,
    concurrency: 10,
  },
  pages: localizedPages,
}),

      ], });

      plaintext
      
然后，创建一个 `src/routes/sitemap[.]xml.ts` 路由，使用 `generateSitemap` 函数：

      `typescript fileName="src/routes/sitemap[.]xml.ts"

      export const Route = createFileRoute("/sitemap.xml")({ server: {

      plaintext
      handlers: {
  GET: async () => {
    const sitemap = generateSitemap(
      [
        { path: "/", changefreq: "daily", priority: 1.0 },
        { path: "/about", changefreq: "monthly", priority: 0.8 },
      ],
      { siteUrl: SITE_URL }
    );

    return new Response(sitemap, {
      headers: { "Content-Type": "application/xml" },
    });
  },
},

      }, }); { // ... 你现有的配置 include: [

      plaintext
      // ... 你现有的 includes
".intlayer/**/*.ts", // 包含自动生成的类型

      ], }

      Git 配置

      建议忽略由 Intlayer 生成的文件。这样可以避免将它们提交到 Git 仓库。

      为此，您可以将以下指令添加到您的 .gitignore 文件中：

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

      `

      VS Code 扩展

      为了改进你使用 Intlayer 的开发体验，你可以安装官方的 Intlayer VS Code 扩展。

      从 VS Code 应用市场安装

      此扩展提供以下功能：

      • 自动完成翻译密钥。
      • 实时错误检测缺失的翻译。
      • 内联预览已翻译的内容。
      • 快速操作轻松创建和更新翻译。

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

      更进一步

      要更进一步，您可以实现可视化编辑器或使用CMS外部化您的内容。

      文档参考

      编译器Tanstack Start Solid