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

    使用 Intlayer 翻译您的 Tanstack Start + Solid.js 网站 | 国际化 (i18n)

    目录

    本指南演示了如何集成 Intlayer，以便在包含 Solid.js 的 Tanstack Start 项目中实现无缝国际化、本地化感知路由、TypeScript 支持以及现代开发实践。

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

    与 react-i18next 或 i18next 等主要解决方案相比，Intlayer 是一个附带集成优化的解决方案，例如：

    Intlayer 经过优化，可与 TanStack Start 和 Solid 完美配合，提供多语言路由、站点地图以及扩展国际化 (i18n) 所需的所有功能。

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

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

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

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

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

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

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

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

    参见 GitHub 上的应用模板。

    1. 创建项目

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

    2. 安装 Intlayer 包

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

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

      • intlayer

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

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

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

    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、中间件重定向、cookie 名称、内容声明的位置和扩展名、禁用控制台中的 Intlayer 日志等。关于可用参数的完整列表，请参考配置文档。

    4. 在您的 Vite 配置中集成 Intlayer

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

      vite.config.ts
      import { intlayer } from "vite-intlayer";
import { defineConfig } from "vite";
import { devtools } from "@tanstack/devtools-vite";
import { tanstackStart } from "@tanstack/solid-start/plugin/vite";
import solidPlugin from "vite-plugin-solid";

export default defineConfig({
  plugins: [
    devtools(),
    tanstackStart({
      router: {
        routeFileIgnorePattern:
          ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5|md|mdx|yaml|yml)$",
      },
    }),
    solidPlugin({ ssr: true }),
    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
  ],
});
      intlayer() Vite 插件用于将 Intlayer 与 Vite 集成。它确保内容声明文件的构建并在开发模式下监控它们。它在 Vite 应用程序中定义 Intlayer 环境变量。此外，它提供别名以优化性能。

    5. 创建根布局

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

      src/routes/__root.tsx
      import {
  HeadContent,
  Scripts,
  createRootRouteWithContext,
  getRouteApi,
} from "@tanstack/solid-router";
import { HydrationScript } from "solid-js/web";
import { Suspense, type ParentComponent } from "solid-js";
import { IntlayerProvider } from "solid-intlayer";
import { defaultLocale, getHTMLTextDir } from "intlayer";

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

export const Route = createRootRouteWithContext()({
  shellComponent: RootComponent,
});

const RootComponent: ParentComponent = (props) => {
  const params = localeRoute.useParams();
  const locale = params()?.locale ?? defaultLocale;

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

    6. 创建语言环境布局

      创建一个处理语言环境前缀并执行验证的布局。此布局将确保仅处理有效的语言环境。

      如果您不需要在路由级别验证语言环境前缀，此步骤是可选的。
      src/routes/{-$locale}/route.tsx
      import { createFileRoute, Outlet, redirect } from "@tanstack/solid-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 },
        replace: true,
      });
    }
  },
  component: Outlet,
});
      此处，{-$locale} 是一个动态路由参数，将被替换为当前的语言环境。这种符号使 slot 成为可选的，允许它与诸如 'prefix-no-default' 等路由模式一起使用。

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

    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/LocalizedLink.tsx
      import { Link, type LinkProps } from "@tanstack/solid-router";
import { getPrefix } from "intlayer";
import { useLocale } from "solid-intlayer";
import type { JSX } from "solid-js";

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

export type RemoveLocaleParam<TVal> = TVal extends string
  ? RemoveLocaleFromString<TVal>
  : TVal;

export type To = RemoveLocaleParam<LinkProps["to"]>;

type CollapseDoubleSlashes<TString extends string> =
  TString extends `${infer THead}//${infer TTail}`
    ? CollapseDoubleSlashes<`${THead}/${TTail}`>
    : TString;

export type LocalizedLinkProps = Omit<LinkProps, "to"> & {
  to?: To;
} & JSX.AnchorHTMLAttributes<HTMLAnchorElement>;

type RemoveAll<
  TString extends string,
  TSub extends string,
> = TString extends `${infer THead}${TSub}${infer TTail}`
  ? RemoveAll<`${THead}${TTail}`, TSub>
  : TString;

type RemoveLocaleFromString<TString extends string> = CollapseDoubleSlashes<
  RemoveAll<TString, typeof LOCALE_ROUTE>
>;

export const LocalizedLink = (props: LocalizedLinkProps) => {
  const { locale } = useLocale();

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

      此组件有两个目标：

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

      然后我们可以创建一个 useLocalizedNavigate hook 用于编程导航：

      src/hooks/useLocalizedNavigate.tsx
      import { useNavigate } from "@tanstack/solid-router";
import { getLocalizedUrl } from "intlayer";
import { useLocale } from "solid-intlayer";

export const useLocalizedNavigate = () => {
  const navigate = useNavigate();
  const { locale } = useLocale();

  const localizedNavigate = (to: string) => {
    const localizedTo = getLocalizedUrl(to, locale());
    return navigate({ to: localizedTo });
  };

  return localizedNavigate;
};

    9. 在您的页面中使用 Intlayer

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

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

      本地化主页

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

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

function RouteComponent() {
  const content = useIntlayer("index-page");

  return (
    <main>
      <h1>{content.heroTitle}</h1>
      <p>{content.heroDesc}</p>
      <div>
        <LocalizedLink to="/">{content.navHome}</LocalizedLink>
        <LocalizedLink to="/about">{content.navAbout}</LocalizedLink>
      </div>
    </main>
  );
}

      在 Solid 中，useIntlayer 返回反应式内容（例如 content）。您可以直接访问其属性。

      如果您想在 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/LocaleSwitcher.tsx
      import { useLocation } from "@tanstack/solid-router";
import { getLocaleName, getPathWithoutLocale, getPrefix } from "intlayer";
import { For } from "solid-js";
import { useIntlayer, useLocale } from "solid-intlayer";
import { LocalizedLink, type To } from "./LocalizedLink";

export const LocaleSwitcher = () => {
  const content = useIntlayer("locale-switcher");
  const location = useLocation();

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

  const pathWithoutLocale = () => getPathWithoutLocale(location().pathname);

  return (
    <div class="flex flex-row gap-2">
      <For each={availableLocales}>
        {(localeEl) => (
          <LocalizedLink
            aria-current={localeEl === locale() ? "page" : undefined}
            onClick={() => setLocale(localeEl)}
            params={{ locale: getPrefix(localeEl).localePrefix }}
            to={pathWithoutLocale() as To}
          >
            {getLocaleName(localeEl)}
          </LocalizedLink>
        )}
      </For>
    </div>
  );
};

export default LocaleSwitcher;

      在 Solid 中，来自 useLocale 的 locale 是一个信号访问器。使用 locale()（带括号）以反应式方式读取其当前值。

      要了解更多关于 useLocale hook 的信息，请参考文档。

    11. HTML 属性管理

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

      src/routes/__root.tsx
      const RootComponent: ParentComponent = (props) => {
  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/solid-start/plugin/vite";
import solid from "vite-plugin-solid";
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)$",
      },
    }),
    solid(),
  ],
});

    13. 国际化您的元数据

      getIntlayer 会同步地在合并后的字典上解析，也就是包含所有已声明语言环境的那一份。head 保持同步、无需等待，但整个多语言字典都会被打进发送到浏览器的路由分块中。

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

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

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

    return {
      links: [
        // Canonical link: Points to the current localized page
        { rel: "canonical", href: getLocalizedUrl(path, locale) },

        // Hreflang: Tell Google about all localized versions
        ...localeMap(({ locale: mapLocale }) => ({
          rel: "alternate",
          hrefLang: mapLocale,
          href: getLocalizedUrl(path, mapLocale),
        })),

        // x-default: For users in unmatched languages
        // Define the default fallback locale (usually your primary language)
        {
          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/solid-router";
import {
  defaultLocale,
  getIntlayerAsync,
  getLocalizedUrl,
  localeMap,
} from "intlayer";

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

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

    return {
      links: [
        // Canonical link: Points to the current localized page
        { rel: "canonical", href: getLocalizedUrl(path, locale) },

        // Hreflang: Tell Google about all localized versions
        ...localeMap(({ locale: mapLocale }) => ({
          rel: "alternate",
          hrefLang: mapLocale,
          href: getLocalizedUrl(path, mapLocale),
        })),

        // x-default: For users in unmatched languages
        // Define the default fallback locale (usually your primary language)
        {
          rel: "alternate",
          hrefLang: "x-default",
          href: getLocalizedUrl(path, defaultLocale),
        },
      ],
      meta: [
        { title: metaContent.title },
        { name: "description", content: metaContent.meta.description },
      ],
    };
  },
});
      如果一个 head 要读取多个字典，请用 Promise.all 一并解析；逐行 await 每个 getIntlayerAsync 会把请求串成链式调用，而不是并行执行。

      代价是：动态 import 会在 head 执行期间解析，处于文档渲染的关键路径上。在冷路由上这会让 head 延迟几毫秒，并可能略微拉低 LCP。

      改为在路由的 loader 中解析字典，再于 head 中通过 loaderData 读回。已匹配路由的 loader 会并行运行，而 staleTime: Infinity 告诉 TanStack Router 该结果永不过期，于是按语言环境的分块只解析一次，之后由路由缓存提供，head 得以保持同步。

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

export const Route = createFileRoute("/{-$locale}/")({
  component: RouteComponent,
  // Resolved in parallel with the other matched routes, off the head critical path
  loader: async ({ params }) => {
    const { locale = defaultLocale } = params;

    return { metaContent: await getIntlayerAsync("app", locale) };
  },
  // The dictionary never changes for a given locale: resolve the chunk once
  staleTime: Infinity,
  head: ({ params, loaderData }) => {
    const { locale = defaultLocale } = params;
    const path = "/"; // The path for this route

    return {
      links: [
        // Canonical link: Points to the current localized page
        { rel: "canonical", href: getLocalizedUrl(path, locale) },

        // Hreflang: Tell Google about all localized versions
        ...localeMap(({ locale: mapLocale }) => ({
          rel: "alternate",
          hrefLang: mapLocale,
          href: getLocalizedUrl(path, mapLocale),
        })),

        // x-default: For users in unmatched languages
        // Define the default fallback locale (usually your primary language)
        {
          rel: "alternate",
          hrefLang: "x-default",
          href: getLocalizedUrl(path, defaultLocale),
        },
      ],
      meta: [
        { title: loaderData?.metaContent.title },
        {
          name: "description",
          content: loaderData?.metaContent.meta.description,
        },
      ],
    };
  },
});
      head 可能在 loader 完成之前被调用，因此 loaderData 的类型可能为 undefined。请保留可选链，或返回一个兜底标题。

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

      该选择哪种解析方式？

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

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

      您可能希望从服务器操作或 API 端点内部访问当前语言环境。 您可以使用 intlayer 中的 getLocale helper。

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

      src/routes/{-$locale}/index.tsx
      import { createServerFn } from "@tanstack/solid-start";
import {
  getRequestHeader,
  getRequestHeaders,
} from "@tanstack/solid-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),
  });

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

  return { locale, content };
});

    15. 管理未找到页面

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

      理解 TanStack Router 的 404 处理与区域设置前缀

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

      1. 专用 404 路由：用于显示 404 UI 的特定路由
      2. 路由级验证：验证区域设置前缀并将无效的前缀重定向到 404
      3. 全能路由：捕获区域设置段内所有不匹配的路径
      src/routes/{-$locale}/404.tsx
      import { createFileRoute } from "@tanstack/solid-router";

// 这创建了一个专用的 /[locale]/404 路由
// 它既可用作直接路由，也可在其他文件中作为组件导入
export const Route = createFileRoute("/{-$locale}/404")({
  component: NotFoundComponent,
});

// 单独导出，以便在 notFoundComponent 和全能路由中重用
export function NotFoundComponent() {
  return (
    <div>
      <h1>404</h1>
    </div>
  );
}
      src/routes/{-$locale}/route.tsx
      import { createFileRoute, Outlet, redirect } from "@tanstack/solid-router";
import { validatePrefix } from "intlayer";
import { NotFoundComponent } from "./404";

export const Route = createFileRoute("/{-$locale}")({
  // beforeLoad 在路由渲染前运行（在服务器和客户端上）
  // 这是验证区域设置前缀的理想位置
  beforeLoad: ({ params }) => {
    const localeParam = params.locale;

    // validatePrefix 检查区域设置是否根据你的 intlayer 配置有效
    const { isValid, localePrefix } = validatePrefix(localeParam);

    if (!isValid) {
      // 无效的区域设置前缀 - 使用有效的区域设置前缀重定向到 404 页面
      throw redirect({
        to: "/{-$locale}/404",
        params: { locale: localePrefix },
      });
    }
  },
  component: Outlet,
  // notFoundComponent 在子路由不存在时被调用
  // 例如，/en/non-existent-page 在 /en 布局内触发这个
  notFoundComponent: NotFoundComponent,
});
      src/routes/{-$locale}/$.tsx
      import { createFileRoute } from "@tanstack/solid-router";

import { NotFoundComponent } from "./404";

// $ (splat/全能) 路由匹配任何不匹配其他路由的路径
// 例如，/en/some/deeply/nested/invalid/path
// 这确保区域设置内的所有不匹配路径都显示 404 页面
// 没有这个，不匹配的深层路径可能会显示空白页或错误
export const Route = createFileRoute("/{-$locale}/$")({
  component: NotFoundComponent,
});

    16. 提取你的组件内容

      可选

      如果你有现有的代码库，转换数千个文件可能很耗时。

      为了简化这个过程，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()` 函数调用，并保持基础代码库完整。转换将仅在内存中完成。
     */
    saveComponents: false,

    /**
     * 字典键前缀
     */
    dictionaryKeyPrefix: "",
  },
};

export default config;

      运行提取器来转换你的组件和提取内容

      bash
      npx intlayer extract
      从 v9 开始，intlayerCompiler 已包含在 intlayer 插件中。所以你不需要手动添加它。

      更新你的 vite.config.ts 以包含 intlayerCompiler 插件：

      vite.config.ts
      import { intlayer, intlayerCompiler } from "vite-intlayer";
import { defineConfig } from "vite";
import { devtools } from "@tanstack/devtools-vite";
import { tanstackStart } from "@tanstack/solid-start/plugin/vite";
import solidPlugin from "vite-plugin-solid";

export default defineConfig({
  plugins: [
    devtools(),
    tanstackStart({
      router: {
        routeFileIgnorePattern:
          ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5|md|mdx|yaml|yml)$",
      },
    }),
    solidPlugin({ ssr: true }),
    intlayer(),
    intlayerCompiler(), // 添加编译器插件
  ],
});
      bash
      npm run build # 或 npm run dev

    17. 预渲染和生成 Sitemap

      Intlayer 配备了内置的 sitemap 生成器，可以帮助你轻松为应用创建 sitemap。它处理本地化路由并为搜索引擎添加必要的元数据。

      Intlayer 生成的 sitemap 支持 xhtml:link 命名空间（Hreflang XML 扩展）。与仅列出原始 URL 的默认 sitemap 生成器不同，Intlayer 会自动创建页面所有语言版本之间所需的双向链接（例如 /about、/about?lang=fr 和 /about?lang=es）。这确保搜索引擎正确索引并为正确的受众提供正确的语言版本。

      要使用它，你首先需要配置你的 vite.config.ts 以启用本地化路由的预渲染并禁用默认的 TanStack Start sitemap 生成。

      vite.config.ts
      import { localeMap, localeFlatMap } from "intlayer";
// ... 其他导入

export const pathList = ["", "/about", "/404"];

const localizedPages = localeFlatMap(({ urlPrefix }) =>
  pathList.map((path) => ({
    path: `${urlPrefix}${path}`,
    prerender: {
      enabled: true,
    },
  }))
);

export default defineConfig({
  plugins: [
    // ... 其他插件
    tanstackStart({
      // ... 其他配置
      sitemap: {
        enabled: false,
      },
      prerender: {
        enabled: true,
        crawlLinks: false,
        concurrency: 10,
      },
      pages: localizedPages,
    }),
  ],
});

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

      src/routes/sitemap[.]xml.ts
      import { createFileRoute } from "@tanstack/solid-router";
import { generateSitemap } from "intlayer";

const SITE_URL = "http://localhost:3000";

export const Route = createFileRoute("/sitemap.xml")({
  server: {
    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" },
        });
      },
    },
  },
});

    18. 配置 TypeScript

      Intlayer 使用模块扩展来获得 TypeScript 的好处并使你的代码库更强大。

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

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

    Git 配置

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

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

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

    VS Code 扩展

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

    从 VS Code 市场安装

    此扩展提供：

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

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

    深入探索

    如需深入了解，您可以实现可视化编辑器或使用 CMS 外置您的内容。

    文档参考

    常见问题

    TanStack Start 本身不包含 i18n 层，而在 Solid 生态中可用的选择相对有限：

    • @solid-primitives/i18n：扁平化字典，需要您自行组装并手动接入路由器。
    • 带有 Solid 封装的 i18next：成熟的目录体系，但未与 TanStack 路由器、head 函数或预渲染流程深度集成。
    • Paraglide：编译型消息，仅专注于消息层。
    • Intlayer：最先进的解决方案。内容可以在代码库中的任何位置声明（靠近每个组件或集中管理），在构建时编译，提供支持语言环境的路由、站点地图生成、AI 翻译、可视化编辑器和 CMS。

    请参阅 为什么选择 Intlayer 和 TanStack Start i18n 性能基准。

    远少于基于命名空间的方案，因为页面永远不会下载它不渲染的语言目录。服务端渲染的标记在服务端直接解析内容，构建时编译器将 useIntlayer 调用替换为组件使用的确切字典条目，因此未使用的键和未使用的语言都会被自动丢弃，并且 动态字典 会按语言环境拆分剩余内容。与常规替代方案相比，Intlayer 可将 bundle 和页面体积减少高达 50%。请参阅 Bundle 体积优化 和 性能基准。

    基本可以。请按照 i18next 迁移指南 迁移内容。您也可以逐步迁移：JSON 同步插件 将您现有的 JSON 目录作为单一真实来源（source of truth），并据此生成 Intlayer 字典，以便在逐步迁移组件时两个层始终保持同步。

    可以。JSON 同步插件 将您的 /messages/{locale}/{namespace}.json 文件作为单一真实来源（source of truth），并双向生成 Intlayer 字典。PO 同步插件 对 gettext 目录执行相同的操作，而 按语言环境组织的文件 允许您按语言拆分内容，而不是将所有语言打包到一个文件中。

    不需要。运行 npx intlayer extract，Intlayer 会读取您的组件，提取面向用户的字符串，并在每个组件旁边生成 .content 文件，这样您只需审查 diff，而无需手动逐一复制字符串到语言目录中。本指南的第 15 步详细介绍了此过程。

    如需全自动流程，Intlayer Compiler 可在构建时执行相同操作：它在每次更改时扫描您的 JSX、TSX、Vue 和 Svelte 源代码，生成字典并通过热模块替换 (HMR) 保持同步，因此完全无需手动维护键名。

    开启编译器前有两个限制值得了解：它通过静态分析工作，因此仅在运行时存在的字符串（如 API 错误代码或 CMS 字段）无法被捕获；此外它需要区分用户文本和应用程序逻辑（如 className="active" 或状态代码），在大型代码库中需要少量注解。而 extract 命令 则通过让您参与审查避免了这两个问题。

    共有 5 个工具，均为可选：

    • VS Code 扩展：从 useIntlayer 键跳转到声明它的内容文件，从组件中提取内容，并从命令面板或专属的 Intlayer 选项卡运行 build、fill、test、push 和 pull。
    • LSP 服务器：在任何支持 LSP 的编辑器中提供相同的感知能力，支持跳转到定义、查找所有引用、悬停预览翻译值、键和字段的自动补全，以及在键未声明时发出警告。它还可以解析 i18next、react-i18next、next-intl 和 use-intl 调用，助力平滑迁移。
    • MCP 服务器：向 Cursor、VS Code、Claude Desktop、Claude Code 和 ChatGPT 公开 Intlayer 文档与 CLI，使 AI 助手能够基于最新文档进行准确回答，并能自行运行 intlayer fill 等命令。
    • Agent Skills：针对特定领域的技能（如 intlayer-config、intlayer-cli 和 intlayer-content，以及每个框架对应的专属技能），教导 AI 代理您的路由配置和内容节点类型。
    • ESLint 插件：no-raw-text 规则标记硬编码字符串，并提供针对静态字典键和未使用内容的额外规则。
    Tanstack StartAstro