@intlayer/docs 9.1.3 → 9.3.0

package/docs/zh/intlayer_with_tanstack.md

@@ -90,9 +90,306 @@ Intlayer 不仅仅是一个 i18n 解决方案，还提供了一个**自托管的
 
 ---
 
-### 第八步：创建支持多语言的组件和钩子
+## 在 Tanstack Start 应用程序中设置 Intlayer 的分步指南
 
-创建一个用于多语言导航的 `LocalizedLink` 组件：
+<Tabs defaultTab="video">
+  <Tab label="Video" value="video">
+
+<iframe title="The best i18n solution for Tanstack Start? Discover Intlayer" class="m-auto aspect-16/9 w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/_XTdKVWaeqg?autoplay=0&amp;origin=https://intlayer.org&amp;controls=0&amp;rel=1"/>
+
+  </Tab>
+  <Tab label="Code" value="code">
+
+<iframe
+  src="https://ide.intlayer.org/aymericzip/intlayer-tanstack-start-template?file=intlayer.config.ts"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="Demo CodeSandbox - How to Internationalize your application using Intlayer"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
+  </Tab>
+  <Tab label="Demo" value="demo">
+
+<iframe
+  src="https://intlayer-tanstack-start-template.vercel.app"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="Demo - intlayer-tanstack-start-template"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
+  </Tab>
+</Tabs>
+
+在 GitHub 上查看 [应用程序模板](https://github.com/aymericzip/intlayer-tanstack-start-template)。
+
+<Steps>
+
+<Step number={1} title="创建项目">
+
+首先，按照 TanStack Start 网站上的 [开始新项目](https://tanstack.com/start/latest/docs/framework/react/quick-start) 指南创建一个新的 TanStack Start 项目。
+
+</Step>
+
+<Step number={2} title="安装 Intlayer 包">
+
+使用您首选的包管理器安装必要的包：
+
+```bash packageManager="npm"
+npx intlayer init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer@canary init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer@canary init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer@canary init --interactive
+```
+
+> `--interactive` 标志是可选的。如果您是 AI 代理，请使用 `intlayer-cli init`。
+
+> 此命令将检测您的环境并安装所需的包。例如：
+
+```bash packageManager="npm"
+npm install intlayer react-intlayer
+npm install vite-intlayer --save-dev
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer react-intlayer
+pnpm add vite-intlayer --save-dev
+```
+
+```bash packageManager="yarn"
+yarn add intlayer react-intlayer
+yarn add vite-intlayer --save-dev
+```
+
+```bash packageManager="bun"
+bun add intlayer react-intlayer
+bun add vite-intlayer --dev
+```
+
+- **intlayer**
+
+  核心包，为配置管理、翻译、[内容声明](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/content_file.md)、转译和 [CLI 命令](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/index.md) 提供国际化工具。
+
+- **react-intlayer**
+  将 Intlayer 与 React 应用程序集成的包。为 React 国际化提供上下文提供程序和 hooks。
+
+- **vite-intlayer**
+  包含用于将 Intlayer 与 [Vite bundler](https://vite.dev/guide/why.html#why-bundle-for-production) 集成的 Vite 插件，以及用于检测用户首选语言、管理 cookies 和处理 URL 重定向的 middleware。
+
+</Step>
+
+<Step number={3} title="配置您的项目">
+
+创建一个配置文件来配置您应用程序的语言：
+
+```typescript fileName="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 日志等。有关可用参数的完整列表，请参考 [配置文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)。
+
+</Step>
+
+<Step number={4} title="在 Vite 配置中集成 Intlayer">
+
+将 intlayer 插件添加到您的配置中：
+
+```typescript fileName="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 环境变量。此外，它提供别名来优化性能。
+
+</Step>
+
+<Step number={5} title="创建根布局">
+
+配置您的根布局以支持国际化，使用 `useParams` 检测当前语言，并在 `html` 标签上设置 `lang` 和 `dir` 属性。
+
+```tsx fileName="src/routes/__root.tsx"
+import {
+  createRootRouteWithContext,
+  HeadContent,
+  Scripts,
+} from "@tanstack/react-router";
+import { defaultLocale, getHTMLTextDir } from "intlayer";
+import { type ReactNode } from "react";
+import { IntlayerProvider } from "react-intlayer";
+import { Route as LocaleRoute } from "./{-$locale}/route";
+
+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>
+  );
+}
+```
+
+</Step>
+
+<Step number={6} title="创建语言布局">
+
+创建一个处理语言前缀并执行验证的布局。
+
+```tsx fileName="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'` 模式，您可以完全移除该插槽。
+
+</Step>
+
+<Step number={7} title="声明您的内容">
+
+创建和管理您的内容声明以存储翻译：
+
+```tsx fileName="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}`）。
+
+> 有关更多详情，请参考 [内容声明文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/content_file.md)。
+
+</Step>
+
+<Step number={7} title="创建语言感知组件和 Hooks">
+
+为语言感知导航创建一个 `LocalizedLink` 组件：
 
 ```tsx fileName="src/components/localized-link.tsx"
 import type { FC } from "react";
@@ -106,8 +403,7 @@ 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}`
+  `/${typeof LOCALE_ROUTE}/` | `/${typeof LOCALE_ROUTE}`
   ? "/"
   : T extends `/${typeof LOCALE_ROUTE}/${infer Rest}`
     ? `/${Rest}`
@@ -134,12 +430,12 @@ export const LocalizedLink: FC<LocalizedLinkProps> = (props) => {
 };
 ```
 
-该组件有两个目标：
+此组件有两个目标：
 
-- 移除 URL 中不必要的 `{-$locale}` 前缀。
-- 将 locale 参数注入 URL，确保用户被直接重定向到本地化路由。
+- 从 URL 中删除不必要的 `{-$locale}` 前缀。
+- 将语言参数注入到 URL 中，以确保用户直接重定向到本地化路由。
 
-接下来我们可以创建一个用于编程导航的 `useLocalizedNavigate` 钩子：
+然后我们可以创建一个 `useLocalizedNavigate` hook 来进行编程导航：
 
 ```tsx fileName="src/hooks/useLocalizedNavigate.tsx"
 import { useNavigate } from "@tanstack/react-router";
@@ -194,9 +490,69 @@ export const useLocalizedNavigate = () => {
 };
 ```
 
-### 第十步：创建语言切换组件
+</Step>
+
+<Step number={8} title="在您的页面中使用 Intlayer">
+
+在整个应用程序中访问您的内容字典：
+
+#### 本地化首页
+
+```tsx fileName="src/routes/{-$locale}/index.tsx"
+import { createFileRoute } from "@tanstack/react-router";
+import { getIntlayer, defaultLocale } from "intlayer";
+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 的信息，请参考[文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/react-intlayer/useIntlayer.md)。
+
+</Step>
+
+<Step number={9} title="创建语言切换器组件">
+
+创建一个组件来允许用户改变语言：
 
 ```tsx fileName="src/components/locale-switcher.tsx"
 import { useLocation } from "@tanstack/react-router";
@@ -230,19 +586,19 @@ export const LocaleSwitcher: FC = () => {
             to={pathWithoutLocale as To}
           >
             <span>
-              {/* 语言环境 - 例如 FR */}
+              {/* 区域设置 - 例如 FR */}
               {localeEl}
             </span>
             <span>
-              {/* 语言在其自身语言环境中的名称 - 例如 Français */}
+              {/* 该语言用其自身区域设置表示 - 例如 Français */}
               {getLocaleName(localeEl, locale)}
             </span>
             <span dir={getHTMLTextDir(localeEl)} lang={localeEl}>
-              {/* 语言在当前语言环境中的名称 - 例如当前语言环境为 Locales.SPANISH 时显示 Francés */}
+              {/* 该语言用当前区域设置表示 - 例如当前区域设置为 Locales.SPANISH 时的 Francés */}
               {getLocaleName(localeEl)}
             </span>
             <span dir="ltr" lang={Locales.ENGLISH}>
-              {/* 语言的英文名称 - 例如 French */}
+              {/* 该语言用英文表示 - 例如 French */}
               {getLocaleName(localeEl, Locales.ENGLISH)}
             </span>
           </LocalizedLink>
@@ -253,15 +609,346 @@ export const LocaleSwitcher: FC = () => {
 };
 ```
 
-> 要了解有关 `useLocale` 钩子的更多信息，请参阅[文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/react-intlayer/useLocale.md)。
+> 要了解更多关于 `useLocale` hook 的信息，请参考[文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/react-intlayer/useLocale.md)。
+
+</Step>
+
+<Step number={10} title="HTML 属性管理">
+
+如第 5 步所示，你可以在根组件中使用 `useParams` 来管理 `html` 标签的 `lang` 和 `dir` 属性。这确保在服务器和客户端上都设置了正确的属性。
+
+```tsx fileName="src/routes/__root.tsx"
+function RootDocument({ children }: { children: ReactNode }) {
+  const params = LocaleRoute.useParams();
+  const locale = params?.locale ?? defaultLocale;
+
+  return (
+    <html dir={getHTMLTextDir(locale)} lang={locale}>
+      {/* ... */}
+    </html>
+  );
+}
+```
+
+---
+
+</Step>
+
+<Step number={11} title="添加中间件">
+
+你也可以使用 `intlayerProxy` 为你的应用程序添加服务器端路由。这个插件将自动基于 URL 检测当前的语言区域并设置适当的语言区域 cookie。如果没有指定区域设置，该插件将根据用户的浏览器语言首选项确定最合适的区域设置。如果没有检测到区域设置，它将重定向到默认的区域设置。
+
+> 请注意，要在生产环境中使用 `intlayerProxy`，你需要将 `vite-intlayer` package 从 `devDependencies` 切换到 `dependencies`。
+
+> 自 Intlayer v9 起，`intlayerProxy()` 直接捆绑到 `intlayer()` 插件中，并通过 `routing.enableProxy` 选项默认启用（默认为 `true`）。如下所示单独注册现在是可选的 — 它保留用于向后兼容性和需要控制插件顺序的设置。设置 `routing.enableProxy: false` 以退出。请参阅 [v9 发布说明](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/releases/v9.md)。
+
+```typescript fileName="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(),
+  ],
+});
+```
+
+---
+
+</Step>
+
+<Step number={12} title="国际化你的元数据">
+
+你也可以使用 `getIntlayer` hook 在整个应用程序中访问你的内容字典：
+
+```tsx fileName="src/routes/{-$locale}/index.tsx"
+import { createFileRoute } from "@tanstack/react-router";
+import { getIntlayer } from "intlayer";
+
+export const Route = createFileRoute("/{-$locale}/")({
+  component: RouteComponent,
+  head: ({ params }) => {
+    const { locale } = 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 },
+      ],
+    };
+  },
+});
+```
+
+---
+
+</Step>
+
+<Step number={13} title="在服务器操作中检索区域设置">
+
+你可能想要从服务器操作或 API 端点内访问当前的区域设置。
+你可以使用来自 `intlayer` 的 `getLocale` helper。
+
+以下是使用 TanStack Start 的服务器函数的示例：
+
+```tsx fileName="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);
+    },
+    // 从请求中获取 header（默认：'x-intlayer-locale'）
+    // 使用 Accept-Language 协商进行回退
+    getHeader: (name) => getRequestHeader(name),
+  });
+
+  // 使用 getIntlayer() 检索一些内容
+  const content = getIntlayer("app", locale);
+
+  return { locale, content };
+});
+```
+
+---
+
+</Step>
+
+<Step number={14} title="管理未找到页面">
+
+当用户访问不存在的页面时，你可以显示自定义的未找到页面，语言区域前缀可能会影响未找到页面的触发方式。
+
+#### 理解 TanStack Router 的 404 处理与 Locale 前缀
+
+在 TanStack Router 中，处理带本地化路由的 404 页面需要采用多层方法：
+
+1. **专用 404 路由**：用于显示 404 UI 的特定路由
+2. **路由级验证**：验证 locale 前缀并将无效的前缀重定向到 404
+3. **捕获所有路由**：捕获 locale 段内任何不匹配的路径
+
+```tsx fileName="src/routes/{-$locale}/404.tsx"
+import { createFileRoute } from "@tanstack/react-router";
+
+// 这创建了一个专用的 /[locale]/404 路由
+// 它既可以作为直接路由使用，也可以作为组件导入到其他文件中
+export const Route = createFileRoute("/{-$locale}/404")({
+  component: NotFoundComponent,
+});
+
+// 单独导出以便在 notFoundComponent 和捕获所有路由中重复使用
+export function NotFoundComponent() {
+  return (
+    <div>
+      <h1>404</h1>
+    </div>
+  );
+}
+```
+
+```tsx fileName="src/routes/{-$locale}/route.tsx"
+import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";
+import { validatePrefix } from "intlayer";
+import { NotFoundComponent } from "./404";
+
+export const Route = createFileRoute("/{-$locale}")({
+  // beforeLoad 在路由渲染前运行（在服务器和客户端上）
+  // 这是验证 locale 前缀的理想位置
+  beforeLoad: ({ params }) => {
+    const localeParam = params.locale;
+
+    // validatePrefix 检查 locale 是否根据你的 intlayer 配置有效
+    const { isValid, localePrefix } = validatePrefix(localeParam);
+
+    if (!isValid) {
+      // 无效的 locale 前缀 - 重定向到 404 页面并使用有效的 locale 前缀
+      throw redirect({
+        to: "/{-$locale}/404",
+        params: { locale: localePrefix },
+      });
+    }
+  },
+  component: Outlet,
+  // notFoundComponent 在子路由不存在时调用
+  // 例如：/en/non-existent-page 在 /en 布局内触发此方法
+  notFoundComponent: NotFoundComponent,
+});
+```
+
+```tsx fileName="src/routes/{-$locale}/$.tsx"
+import { createFileRoute } from "@tanstack/react-router";
+
+import { NotFoundComponent } from "./404";
+
+// $ (splat/catch-all) 路由匹配任何不匹配其他路由的路径
+// 例如：/en/some/deeply/nested/invalid/path
+// 这确保 locale 内所有不匹配的路径都显示 404 页面
+// 没有这个，不匹配的深层路径可能显示空白页面或错误
+export const Route = createFileRoute("/{-$locale}/$")({
+  component: NotFoundComponent,
+});
+```
+
+</Step>
+
+<Step number={15} title="提取组件内容" isOptional={true}>
+
+如果你有现有的 codebase，转换数千个文件可能会很耗时。
+
+为了简化此过程，Intlayer 提供了一个 [compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compiler.md) / [extractor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/extract.md) 来转换你的组件并提取内容。
+
+要设置它，你可以在 `intlayer.config.ts` 文件中添加 `compiler` 部分：
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import { type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  // ... 配置的其余部分
+  compiler: {
+    /**
+     * 表示编译器是否应启用。
+     */
+    enabled: true,
+
+    /**
+     * 定义输出文件路径
+     */
+    output: ({ fileName, extension }) => `./${fileName}${extension}`,
+
+    /**
+     * 表示转换后是否应保存组件。
+     *
+     * - 如果为 `true`，编译器将在磁盘中重写组件文件。因此转换将是永久的，编译器将在下一个过程中跳过转换。这样，编译器可以转换应用程序，然后可以将其删除。
+     *
+     * - 如果为 `false`，编译器将仅在构建输出中注入 `useIntlayer()` 函数调用，并保持 base codebase 完整。转换将仅在内存中完成。
+     */
+    saveComponents: false,
+
+    /**
+     * 字典键前缀
+     */
+    dictionaryKeyPrefix: "",
+  },
+};
+
+export default config;
+```
+
+<Tabs>
+ <Tab value='Extract command'>
+
+运行提取器以转换组件并提取内容
+
+```bash packageManager="npm"
+npx intlayer extract
+```
+
+```bash packageManager="pnpm"
+pnpm intlayer extract
+```
+
+```bash packageManager="yarn"
+yarn intlayer extract
+```
+
+```bash packageManager="bun"
+bun x intlayer extract
+```
+
+ </Tab>
+ <Tab value='Babel compiler'>
+
+> 从 v9 起，`intlayerCompiler` 包含在 `intlayer` 插件中。所以你不需要手动添加它。
 
-### 第十六步：生成站点地图 (Sitemap)（可选）
+更新你的 `vite.config.ts` 以包含 `intlayerCompiler` 插件：
 
-Intlayer 附带一个内置的站点地图生成器，可帮助您轻松为应用程序创建站点地图。它能够处理本地化路由，并为搜索引擎添加必要的元数据。
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { intlayer, intlayerCompiler } from "vite-intlayer";
 
-> Intlayer 生成的站点地图支持 `xhtml:link` 命名空间（Hreflang XML 扩展）。与仅列出原始 URL 的默认站点地图生成器不同，Intlayer 会自动在页面的所有语言版本（例如 `/about`、`/about?lang=fr` 和 `/about?lang=es`）之间创建所需的双向链接。这确保了搜索引擎能够正确索引并向合适的受众提供正确的语言版本。
+export default defineConfig({
+  plugins: [
+    intlayer(),
+    intlayerCompiler(), // 添加编译器插件
+  ],
+});
+```
+
+```bash packageManager="npm"
+npm run build # 或 npm run dev
+```
 
-要使用它，您首先需要配置 `vite.config.ts` 文件，以启用本地化路由的预渲染，并禁用默认的 TanStack Start 站点地图生成。
+```bash packageManager="pnpm"
+pnpm run build # 或 pnpm run dev
+```
+
+```bash packageManager="yarn"
+yarn build # 或 yarn dev
+```
+
+```bash packageManager="bun"
+bun run build # 或 bun run dev
+```
+
+ </Tab>
+</Tabs>
+
+---
+
+</Step>
+
+<Step number={16} title="预渲染 & 生成 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 生成。
 
 ```typescript fileName="vite.config.ts"
 import { localeFlatMap } from "intlayer";
@@ -297,7 +984,7 @@ export default defineConfig({
 });
 ```
 
-然后，创建一个使用 `generateSitemap` 函数的路由 `src/routes/sitemap[.]xml.ts`：
+然后，创建一个 `src/routes/sitemap[.]xml.ts` 路由，使用 `generateSitemap` 函数：
 
 ```typescript fileName="src/routes/sitemap[.]xml.ts"
 import { createFileRoute } from "@tanstack/react-router";
@@ -330,6 +1017,30 @@ export const Route = createFileRoute("/sitemap.xml")({
 
 ---
 
+</Step>
+
+<Step number={17} title="配置 TypeScript">
+
+Intlayer 使用模块扩展以获得 TypeScript 的好处并使你的 codebase 更强大。
+
+确保你的 TypeScript 配置包含自动生成的类型：
+
+```json5 fileName="tsconfig.json"
+{
+  // ... 你现有的配置
+  include: [
+    // ... 你现有的 includes
+    ".intlayer/**/*.ts", // 包含自动生成的类型
+  ],
+}
+```
+
+---
+
+</Step>
+
+</Steps>
+
 ### Git 配置
 
 建议忽略 Intlayer 生成的文件。这样可以避免将它们提交到您的 Git 仓库中。