@intlayer/docs 5.8.1 → 6.0.0-canary.1

package/docs/zh/intlayer_with_tanstack.md

@@ -1,435 +1,625 @@
 ---
-createdAt: 2025-08-11
-updatedAt: 2025-08-11
-title: 在 TanStack Start (React) 中使用 Intlayer 入门
-description: 使用 Intlayer 为您的 TanStack Start 应用添加国际化--组件级字典、本地化 URL 以及 SEO 友好的元数据。
+createdAt: 2025-09-09
+updatedAt: 2025-09-09
+title: 在 Tanstack Start 中使用 Intlayer 入门
+description: 学习如何使用 Intlayer 为您的 Tanstack Start 应用添加国际化 (i18n)。按照本综合指南，使您的应用支持多语言和基于区域设置的路由。
 keywords:
   - 国际化
   - 文档
   - Intlayer
-  - TanStack Start
-  - TanStack Router
+  - Tanstack Start
   - React
   - i18n
-  - JavaScript
+  - TypeScript
+  - 区域路由
 slugs:
   - doc
   - environment
+  - vite-and-react
   - tanstack-start
+applicationTemplate: https://github.com/AydinTheFirst/tanstack-start-intlayer
+author: AydinTheFirst
 ---
 
-# 使用 Intlayer 和 TanStack Start (React) 开始国际化 (i18n)
+# 使用 Intlayer 和 Tanstack Start 开始国际化 (i18n)
+
+本指南演示了如何在 Tanstack Start 项目中集成 **Intlayer**，实现无缝国际化，支持基于区域设置的路由、TypeScript 支持以及现代开发实践。
 
 ## 什么是 Intlayer？
 
-**Intlayer** 是一个针对 React 应用的开源国际化工具包。它为您提供：
+**Intlayer** 是一个创新的开源国际化 (i18n) 库，旨在简化现代 Web 应用中的多语言支持。
 
-- **组件本地字典**，具备 TypeScript 类型安全。
-- **动态元数据和路由**（支持 SEO）。
-- **运行时语言切换**（以及用于检测/持久化语言的辅助工具）。
-- **Vite 插件**，用于构建时转换和开发体验优化。
+使用 Intlayer，您可以：
 
-本指南展示如何将 Intlayer 集成到一个 **TanStack Start** 项目中（该项目底层使用 Vite 和 TanStack Router 进行路由和 SSR）。
+- **通过组件级声明式字典轻松管理翻译**。
+- **动态本地化元数据、路由和内容**。
+- **通过自动生成的类型确保 TypeScript 支持**，提升自动补全和错误检测能力。
+- **享受高级功能**，如动态区域设置检测和切换。
+- **通过 Tanstack Start 的基于文件的路由系统启用区域设置感知路由**。
 
 ---
 
-## 第一步：安装依赖
+## 在 Tanstack Start 应用中设置 Intlayer 的分步指南
 
-```bash
-# npm
-npm i intlayer react-intlayer
-npm i -D vite-intlayer
+### 第一步：创建项目
 
-# pnpm
-pnpm add intlayer react-intlayer
-pnpm add -D vite-intlayer
+首先，按照 TanStack Start 网站上的[创建新项目](https://tanstack.com/start/latest/docs/framework/react/quick-start)指南创建一个新的 TanStack Start 项目。
+
+### 第二步：安装 Intlayer 包
 
-# yarn
-yarn add intlayer react-intlayer
-yarn add -D vite-intlayer
+使用您喜欢的包管理器安装所需的包：
+
+```bash packageManager="npm"
+npm install intlayer react-intlayer
+npm install vite-intlayer --save-dev
 ```
 
-- **intlayer**：核心库（配置、字典、CLI/转换）。
-- **react-intlayer**：`<IntlayerProvider>` 组件及 React 钩子。
-- **vite-intlayer**：Vite 插件，附带可选中间件用于语言检测/重定向（支持开发环境和 SSR/预览；生产 SSR 时需移至 `dependencies`）。
+```bash packageManager="pnpm"
+pnpm add intlayer react-intlayer
+pnpm add vite-intlayer --save-dev
+```
 
----
+- **intlayer**
+
+- **intlayer**
+
+  核心包，提供用于配置管理、翻译、[内容声明](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/get_started.md)、转译和[CLI命令](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_cli.md)的国际化工具。
+
+- **react-intlayer**
+
+  将 Intlayer 集成到 React 应用中的包。它为 React 国际化提供上下文提供者和钩子。
 
-## 第 2 步：配置 Intlayer
+- **vite-intlayer**
 
-在项目根目录创建 `intlayer.config.ts`：
+  包含用于将 Intlayer 集成到[Vite 打包器](https://vite.dev/guide/why.html#why-bundle-for-production)的 Vite 插件，以及用于检测用户首选语言环境、管理 Cookie 和处理 URL 重定向的中间件。
 
-```ts fileName="intlayer.config.ts"
-import { Locales, type IntlayerConfig } from "intlayer";
+### 第三步：项目配置
+
+创建一个配置文件来配置您的应用程序语言：
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import type { IntlayerConfig } from "intlayer";
+
+import { Locales } from "intlayer";
 
 const config: IntlayerConfig = {
   internationalization: {
-    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH], // 支持的语言列表
     defaultLocale: Locales.ENGLISH, // 默认语言
+    locales: [
+      Locales.ENGLISH, // 英语
+      Locales.FRENCH, // 法语
+      Locales.SPANISH, // 西班牙语
+      // 您的其他语言
+    ],
   },
-  // 你也可以调整：contentDir、contentFileExtensions、中间件选项等。
 };
 
 export default config;
 ```
 
-如果你更喜欢 `cjs`/`mjs`，CommonJS/ESM 版本与原文档相同。
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
 
-> 完整配置参考：请参阅 Intlayer 的配置文档。
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    defaultLocale: Locales.ENGLISH, // 默认语言
+    locales: [
+      Locales.ENGLISH, // 英语
+      Locales.FRENCH, // 法语
+      Locales.SPANISH, // 西班牙语
+      // 你的其他语言
+    ],
+  },
+};
 
----
+export default config;
+```
 
-## 第 3 步：添加 Vite 插件（及可选中间件）
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
 
-**TanStack Start 使用 Vite**，因此将 Intlayer 的插件添加到你的 `vite.config.ts`：
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    defaultLocale: Locales.ENGLISH,
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // 你的其他语言
+    ],
+  },
+};
 
-```ts fileName="vite.config.ts"
+module.exports = config;
+```
+
+> 通过此配置文件，您可以设置本地化的 URL、中间件重定向、Cookie 名称、内容声明的位置和扩展名，禁用控制台中的 Intlayer 日志等。有关可用参数的完整列表，请参阅[配置文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)。
+
+### 第4步：在您的 Vite 配置中集成 Intlayer
+
+将 intlayer 插件添加到您的配置中：
+
+```typescript fileName="vite.config.ts" codeFormat="typescript"
+import { reactRouter } from "@react-router/dev/vite";
 import { defineConfig } from "vite";
-import react from "@vitejs/plugin-react-swc";
-import { intlayerPlugin, intLayerMiddlewarePlugin } from "vite-intlayer";
+import { intlayerMiddlewarePlugin, intlayerPlugin } from "vite-intlayer";
+import tsconfigPaths from "vite-tsconfig-paths";
 
 export default defineConfig({
   plugins: [
-    react(),
+    reactRouter(),
+    tsconfigPaths(),
     intlayerPlugin(),
-    // 可选但推荐用于语言环境检测、Cookies 和重定向：
-    intLayerMiddlewarePlugin(),
+    intlayerMiddlewarePlugin(),
   ],
 });
 ```
 
-> 如果你部署 SSR，请将 `vite-intlayer` 移动到 `dependencies`，以便中间件在生产环境中运行。
+> `intlayerPlugin()` 是用于将 Intlayer 集成到 Vite 的插件。它确保内容声明文件的构建，并在开发模式下监控这些文件。它在 Vite 应用中定义了 Intlayer 的环境变量。此外，它还提供别名以优化性能。
 
----
+### 第五步：创建布局组件
 
-## 第 4 步：声明你的内容
+设置你的根布局和特定语言环境的布局：
 
-将你的字典放置在 `./src` 下的任意位置（默认 `contentDir`）。示例：
+#### 根布局
 
-```tsx fileName="src/app.content.tsx"
-import { t, type Dictionary } from "intlayer";
-import type { ReactNode } from "react";
+```tsx fileName="src/routes/{-$locale}/route.tsx" codeFormat="typescript"
+// src/routes/{-$locale}/route.tsx
+import { createFileRoute, Navigate, Outlet } from "@tanstack/react-router";
+import { configuration } from "intlayer";
+import { IntlayerProvider, useLocale } from "react-intlayer";
+
+import { useI18nHTMLAttributes } from "@/hooks/useI18nHTMLAttributes";
+
+export const Route = createFileRoute("/{-$locale}")({
+  component: LayoutComponent,
+});
+
+function LayoutComponent() {
+  const { locale } = Route.useParams();
+
+  return (
+    <IntlayerProvider locale={locale}>
+      <Outlet />
+    </IntlayerProvider>
+  );
+}
+```
+
+### 第6步：声明您的内容
+
+创建并管理您的内容声明以存储翻译：
+
+```tsx fileName="src/contents/page.content.ts" contentDeclarationFormat="typescript"
+import type { Dictionary } from "intlayer";
+
+import { t } from "intlayer";
 
 const appContent = {
-  key: "app",
   content: {
-    viteLogo: t({ en: "Vite logo", fr: "Logo Vite", es: "Logo Vite" }),
-    reactLogo: t({ en: "React logo", fr: "Logo React", es: "Logo React" }),
+    links: {
+      about: t({
+        en: "About",
+        es: "Acerca de",
+        fr: "À propos",
+      }),
+      home: t({
+        en: "首页",
+        es: "Inicio",
+        fr: "Accueil",
+      }),
+    },
+    meta: {
+      description: t({
+        en: "这是一个使用 Intlayer 与 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",
+      }),
+    },
     title: t({
-      en: "TanStack Start + React",
-      fr: "TanStack Start + React",
-      es: "TanStack Start + React",
-    }),
-    count: t({ en: "count is ", fr: "le compte est ", es: "el recuento es " }),
-    edit: t<ReactNode>({
-      en: (
-        <>
-          编辑 <code>src/routes/index.tsx</code> 并保存以测试 HMR
-        </>
-      ),
-      fr: (
-        <>
-          Éditez <code>src/routes/index.tsx</code> et enregistrez pour tester
-          HMR
-        </>
-      ),
-      es: (
-        <>
-          Edita <code>src/routes/index.tsx</code> y guarda para probar HMR
-        </>
-      ),
-    }),
-    readTheDocs: t({
-      en: "点击标志以了解更多",
-      fr: "Cliquez sur les logos pour en savoir plus",
-      es: "Haz clic en los logotipos para saber más",
+      en: "欢迎使用 Intlayer + TanStack Router",
+      es: "Bienvenido a Intlayer + TanStack Router",
+      fr: "Bienvenue à Intlayer + TanStack Router",
     }),
   },
+  key: "app",
 } satisfies Dictionary;
 
 export default appContent;
 ```
 
-JSON/ESM/CJS 变体与您的原始文档中相同。
+> 您的内容声明可以在应用程序中的任何位置定义，只要它们被包含在 `contentDir` 目录中（默认是 `./app`）。并且文件扩展名需匹配内容声明的文件扩展名（默认是 `.content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}`）。
 
-> TSX 内容？如果您的设置需要，别忘了 `import React from "react"`。
+> 更多详情，请参阅[内容声明文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/get_started.md)。
 
----
+### 第7步：创建支持多语言环境的组件和钩子
 
-## 第5步：用 Intlayer 包裹 TanStack Start
+创建一个用于多语言环境导航的 `LocalizedLink` 组件：
 
-使用 TanStack Start，您的**根路由**是设置提供者的正确位置。
+```tsx fileName="src/components/localized-link.tsx" codeFormat="typescript"
+// src/components/localized-link.tsx
+// eslint-disable-next-line no-restricted-imports
+import { Link, type LinkProps } from "@tanstack/react-router";
+import { getLocalizedUrl } from "intlayer";
+import { useLocale } from "react-intlayer";
 
-```tsx fileName="src/routes/__root.tsx"
-import {
-  Outlet,
-  createRootRoute,
-  Link as RouterLink,
-} from "@tanstack/react-router";
-import { IntlayerProvider, useIntlayer } from "react-intlayer";
-
-function AppShell() {
-  // 在顶层使用字典的示例：
-  const content = useIntlayer("app");
+type LocalizedLinkProps = {
+  to: string;
+} & Omit<LinkProps, "to">;
 
-  return (
-    <div>
-      <nav className="flex gap-3 p-3">
-        <RouterLink to="/">首页</RouterLink>
-        <RouterLink to="/about">关于</RouterLink>
-      </nav>
-      <main className="p-6">
-        <h1>{content.title}</h1>
-        <Outlet />
-      </main>
-    </div>
-  );
-}
+export function LocalizedLink(props: LocalizedLinkProps) {
+  const { locale } = useLocale();
 
-export const Route = createRootRoute({
-  component: () => (
-    <IntlayerProvider>
-      <AppShell />
-    </IntlayerProvider>
-  ),
-});
-```
+  const isExternal = (to: string) => {
+    return /^(https?:)?\/\//.test(to);
+  };
 
-然后在页面中使用你的内容：
+  const to = isExternal(props.to)
+    ? props.to
+    : getLocalizedUrl(props.to, locale);
 
-```tsx fileName="src/routes/index.tsx"
-import { createFileRoute } from "@tanstack/react-router";
-import { useIntlayer } from "react-intlayer";
-import reactLogo from "../assets/react.svg";
-
-export const Route = createFileRoute("/")({
-  component: () => {
-    const content = useIntlayer("app");
-    return (
-      <>
-        <button>{content.count}0</button>
-        <p>{content.edit}</p>
-        <img
-          src={reactLogo}
-          alt={content.reactLogo.value}
-          width={48}
-          height={48}
-        />
-        <p className="opacity-70">{content.readTheDocs}</p>
-      </>
-    );
-  },
-});
+  return <Link {...props} to={to as LinkProps["to"]} />;
+}
 ```
 
-> 字符串属性（`alt`，`title`，`aria-label` 等）需要 `.value`：
->
-> ```jsx
-> <img alt={c.reactLogo.value} />
-> ```
+创建一个用于编程式导航的 `useLocalizedNavigate` 钩子：
 
----
+```tsx fileName="src/hooks/useLocalizedNavigate.tsx" codeFormat="typescript"
+// src/hooks/useLocalizedNavigate.tsx
+// eslint-disable-next-line no-restricted-imports
+import { NavigateOptions, useNavigate } from "@tanstack/react-router";
+import { getLocalizedUrl } from "intlayer";
+import { useLocale } from "react-intlayer";
 
-## （可选）步骤 6：语言切换（客户端）
+type LocalizedNavigateOptions = {
+  to: string;
+} & Omit<NavigateOptions, "to">;
 
-```tsx fileName="src/components/LocaleSwitcher.tsx"
-import { Locales } from "intlayer";
-import { useLocale } from "react-intlayer";
+export const useLocalizedNavigate = () => {
+  const navigate = useNavigate();
+  const { locale } = useLocale();
 
-export function LocaleSwitcher() {
-  const { setLocale } = useLocale();
-  return (
-    <div className="flex gap-2">
-      <button onClick={() => setLocale(Locales.ENGLISH)}>English</button>
-      <button onClick={() => setLocale(Locales.FRENCH)}>Français</button>
-      <button onClick={() => setLocale(Locales.SPANISH)}>Español</button>
-    </div>
-  );
-}
+  const isExternal = (to: string) => {
+    return /^(https?:)?\/\//.test(to);
+  };
+
+  const localizedNavigate = (options: LocalizedNavigateOptions) => {
+    const to = isExternal(options.to)
+      ? options.to
+      : getLocalizedUrl(options.to, locale);
+
+    navigate({ ...options, to: to as NavigateOptions["to"] });
+  };
+
+  return localizedNavigate;
+};
 ```
 
----
+### 第8步：在您的页面中使用 Intlayer
 
-## （可选）步骤7：本地化路由（SEO友好URL）
+在整个应用程序中访问您的内容字典：
 
-在 TanStack Start 中，你有**两种不错的模式**。请选择其一。
+#### 根重定向页面
 
-创建一个动态段文件夹 `src/routes/$locale/`，这样你的 URL 就是 `/:locale/...`。在 `$locale` 布局中，验证 `params.locale`，设置 `<IntlayerProvider locale=...>`，并渲染一个 `<Outlet />`。这种方法很直接，但你需要将其余路由挂载在 `$locale` 下面，如果你**不想**让默认语言带前缀，则还需要额外的无前缀路由树。
+```tsx fileName="src/routes/page.tsx" codeFormat="typescript"
+// src/routes/page.tsx
+import { useLocale } from "react-intlayer";
+import { Navigate } from "react-router";
 
----
+export default function Page() {
+  const { locale } = useLocale();
 
-## （可选）步骤 8：切换语言时更新 URL
+  return <Navigate replace to={locale} />;
+}
+```
 
-使用模式 A（basepath），切换语言意味着**导航到不同的 basepath**：
+#### 本地化首页
 
-```tsx fileName="src/components/LocaleSwitcherNavigate.tsx"
-import { useRouter } from "@tanstack/react-router";
-import { Locales, getLocalizedUrl } from "intlayer";
-import { useLocale } from "react-intlayer";
+```tsx fileName="src/routes/{-$locale}/index.tsx" codeFormat="typescript"
+import { createFileRoute } from "@tanstack/react-router";
+import { getIntlayer } from "intlayer";
+import { useIntlayer } from "react-intlayer";
 
-export function LocaleSwitcherNavigate() {
-  const router = useRouter();
-  const { locale, setLocale } = useLocale();
-
-  const change = async (next: Locales) => {
-    if (next === locale) return;
-    const nextPath = getLocalizedUrl(
-      window.location.pathname + window.location.search,
-      next
-    );
-    await router.navigate({ to: nextPath }); // 保留历史记录
-    setLocale(next);
-  };
+import LocaleSwitcher from "@/components/locale-switcher";
+import { LocalizedLink } from "@/components/localized-link";
+import { useLocalizedNavigate } from "@/hooks/useLocalizedNavigate";
+
+export const Route = createFileRoute("/{-$locale}/")({
+  component: RouteComponent,
+  head: ({ params }) => {
+    const { locale } = params;
+    const metaContent = getIntlayer("app", locale);
+
+    return {
+      meta: [
+        { title: metaContent.title },
+        { content: metaContent.meta.description, name: "description" },
+      ],
+    };
+  },
+});
+
+function RouteComponent() {
+  const content = useIntlayer("app");
+  const navigate = useLocalizedNavigate();
 
   return (
-    <div className="flex gap-2">
-      <button onClick={() => change(Locales.ENGLISH)}>English</button>
-      <button onClick={() => change(Locales.FRENCH)}>Français</button>
-      <button onClick={() => change(Locales.SPANISH)}>Español</button>
+    <div className="grid place-items-center h-screen">
+      <div className="flex flex-col gap-4 items-center text-center">
+        {content.title}
+        <LocaleSwitcher />
+        <div className="flex gap-4">
+          <a href="/">索引</a>
+          <LocalizedLink to="/">{content.links.home}</LocalizedLink>
+          <LocalizedLink to="/about">{content.links.about}</LocalizedLink>
+        </div>
+        <div className="flex gap-4">
+          <button onClick={() => navigate({ to: "/" })}>
+            {content.links.home}
+          </button>
+          <button onClick={() => navigate({ to: "/about" })}>
+            {content.links.about}
+          </button>
+        </div>
+      </div>
     </div>
   );
 }
 ```
 
----
+> 想了解更多关于 `useIntlayer` 钩子的内容，请参阅[文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/react-intlayer/useIntlayer.md)。
 
-## （可选）步骤 9：`<html lang>` 和 `dir`（TanStack Start Document）
+### 第9步：创建语言切换组件
 
-TanStack Start 提供了一个可自定义的 **Document**（根 HTML 外壳）。设置 `lang` 和 `dir` 以提升无障碍访问和 SEO：
+创建一个组件，允许用户切换语言：
 
-```tsx fileName="src/routes/__root.tsx" {4,15}
-import { Outlet, createRootRoute } from "@tanstack/react-router";
-import { IntlayerProvider } from "react-intlayer";
-import { getHTMLTextDir } from "intlayer";
+```tsx fileName="src/components/locale-switcher.tsx" codeFormat="typescript"
+import { useLocation } from "@tanstack/react-router";
+import {
+  getHTMLTextDir,
+  getLocaleName,
+  getLocalizedUrl,
+  Locales,
+} from "intlayer";
+import { useIntlayer, useLocale } from "react-intlayer";
+
+export default function LocaleSwitcher() {
+  const { pathname, searchStr } = useLocation();
+  const content = useIntlayer("locale-switcher");
+
+  const { availableLocales, locale, setLocale } = useLocale({
+    onLocaleChange: (newLocale) => {
+      const pathWithLocale = getLocalizedUrl(pathname + searchStr, newLocale);
+      location.replace(pathWithLocale);
+    },
+  });
 
-function Document({
-  locale,
-  children,
-}: {
-  locale: string;
-  children: React.ReactNode;
-}) {
   return (
-    <html lang={locale} dir={getHTMLTextDir(locale)}>
-      <head>
-        <meta charSet="utf-8" />
-        <meta name="viewport" content="width=device-width, initial-scale=1" />
-        {/* ... */}
-      </head>
-      <body>{children}</body>
-    </html>
+    <select
+      aria-label={content.label.toString()}
+      onChange={(e) => setLocale(e.target.value)}
+      value={locale}
+    >
+      {availableLocales.map((localeItem) => (
+        <option
+          dir={getHTMLTextDir(localeItem)}
+          key={localeItem}
+          lang={localeItem}
+          value={localeItem}
+        >
+          {/* 示例：Français（法语） */}
+          {getLocaleName(localeItem, locale)} (
+          {getLocaleName(localeItem, Locales.ENGLISH)})
+        </option>
+      ))}
+    </select>
   );
 }
-
-export const Route = createRootRoute({
-  component: () => (
-    <IntlayerProvider>
-      {/* 如果您在服务器端计算 locale，请将其传递给 Document；否则客户端将在水合后进行修正 */}
-      <Document locale={document?.documentElement?.lang || "en"}>
-        <Outlet />
-      </Document>
-    </IntlayerProvider>
-  ),
-});
 ```
 
-对于客户端修正，您也可以保留您的小钩子：
+> 想了解更多关于 `useLocale` 钩子的内容，请参考[文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/react-intlayer/useLocale.md)。
+
+### 第10步：添加HTML属性管理（可选）
+
+创建一个钩子来管理HTML的lang和dir属性：
 
-```tsx fileName="src/hooks/useI18nHTMLAttributes.tsx"
+```tsx fileName="src/hooks/useI18nHTMLAttributes.tsx" codeFormat="typescript"
+// src/hooks/useI18nHTMLAttributes.tsx
+import { getHTMLTextDir } from "intlayer";
 import { useEffect } from "react";
 import { useLocale } from "react-intlayer";
-import { getHTMLTextDir } from "intlayer";
 
 export const useI18nHTMLAttributes = () => {
   const { locale } = useLocale();
+
   useEffect(() => {
     document.documentElement.lang = locale;
-    document.documentElement.dir = getHTMLTextDir(locale);
+    document.documentElement.dir = getHTMLTextDir(locale); // 设置HTML的文本方向属性
   }, [locale]);
 };
 ```
 
----
+然后在你的根组件中使用它：
 
-## （可选）步骤10：本地化链接组件
+```tsx fileName="src/routes/{-$locale}/index.tsx" codeFormat="typescript"
+import { createFileRoute, Navigate, Outlet } from "@tanstack/react-router";
+import { configuration } from "intlayer";
+import { IntlayerProvider, useLocale } from "react-intlayer";
 
-TanStack Router 提供了一个 `<Link/>`，但如果你需要一个自动为内部 URL 添加前缀的普通 `<a>` 标签：
+import { useI18nHTMLAttributes } from "@/hooks/useI18nHTMLAttributes"; // 导入该hook
 
-```tsx fileName="src/components/Link.tsx"
-import { getLocalizedUrl } from "intlayer";
-import {
-  forwardRef,
-  type AnchorHTMLAttributes,
-  type DetailedHTMLProps,
-} from "react";
-import { useLocale } from "react-intlayer";
+export const Route = createFileRoute("/{-$locale}")({
+  component: LayoutComponent,
+});
 
-export interface LinkProps
-  extends DetailedHTMLProps<
-    AnchorHTMLAttributes<HTMLAnchorElement>,
-    HTMLAnchorElement
-  > {}
-
-const isExternal = (href?: string) => /^https?:\/\//.test(href ?? "");
-
-export const Link = forwardRef<HTMLAnchorElement, LinkProps>(
-  ({ href, children, ...props }, ref) => {
-    const { locale } = useLocale();
-    const hrefI18n =
-      href && !isExternal(href) ? getLocalizedUrl(href, locale) : href;
-    return (
-      <a href={hrefI18n} ref={ref} {...props}>
-        {children}
-      </a>
-    );
-  }
-);
-Link.displayName = "Link";
+function LayoutComponent() {
+  useI18nHTMLAttributes(); // 添加此行
+
+  const { locale } = Route.useParams();
+
+  return (
+    <IntlayerProvider locale={locale}>
+      <Outlet />
+    </IntlayerProvider>
+  );
+}
 ```
 
-> 如果您使用模式 A（basepath），TanStack 的 `<Link to="/about" />` 已经通过 `basepath` 解析为 `/fr/about`，因此自定义链接是可选的。
+### 第11步：构建并运行您的应用程序
 
----
+构建内容字典并运行您的应用程序：
+
+```bash packageManager="npm"
+# 构建 Intlayer 字典
+npm run intlayer:build
 
-## TypeScript
+# 启动开发服务器
+npm run dev
+```
+
+```bash packageManager="pnpm"
+# 构建 Intlayer 字典
+pnpm intlayer:build
+
+# 启动开发服务器
+pnpm dev
+```
+
+```bash packageManager="yarn"
+# 构建 Intlayer 字典
+yarn intlayer:build
 
-包含 Intlayer 生成的类型：
+# 启动开发服务器
+yarn dev
+```
+
+### 第12步：配置 TypeScript（可选）
+
+Intlayer 使用模块增强来利用 TypeScript 的优势，使您的代码库更强大。
+
+确保您的 TypeScript 配置包含自动生成的类型：
 
 ```json5 fileName="tsconfig.json"
 {
-  "include": ["src", ".intlayer/**/*.ts"],
+  compilerOptions: {
+    // ... 您现有的 TypeScript 配置
+  },
+  include: [
+    // ... 您现有的包含项
+    ".intlayer/**/*.ts", // 包含自动生成的类型
+  ],
 }
 ```
 
----
+### Git 配置
 
-## Git
+建议忽略 Intlayer 生成的文件。这样可以避免将它们提交到您的 Git 仓库。
 
-忽略 Intlayer 生成的构建产物：
+为此，您可以将以下指令添加到您的 `.gitignore` 文件中：
 
-```gitignore
+```plaintext fileName=".gitignore"
+# 忽略 Intlayer 生成的文件
 .intlayer
 ```
 
 ---
 
+### 第 13 步：创建重定向（可选）
+
+```typescript fileName="src/routes/{-$locale}/rotue.tsx" codeFormat="typescript"
+function LayoutComponent() {
+  useI18nHTMLAttributes();
+
+  const { locale } = Route.useParams();
+  const { locale: selectedLocale } = useLocale();
+  const { defaultLocale } = configuration.internationalization;
+  const { prefixDefault } = configuration.middleware;
+
+  // 如果 prefixDefault 为 true 且 URL 中没有 locale，则重定向到默认语言
+  if (selectedLocale === defaultLocale && !locale && prefixDefault) {
+    return <Navigate replace to={defaultLocale} />;
+  }
+
+  // 如果 URL 中的 locale 与选定的 locale 不匹配，则重定向到选定的 locale
+  if (selectedLocale !== defaultLocale && !locale) {
+    return <Navigate replace to={selectedLocale} />;
+  }
+
+  return (
+    <IntlayerProvider locale={locale}>
+      <Outlet />
+    </IntlayerProvider>
+  );
+}
+```
+
+## 生产部署
+
+部署您的应用程序时：
+
+1. **构建您的应用程序：**
+
+   ```bash
+   npm run build
+   ```
+
+2. **构建 Intlayer 词典：**
+
+   ```bash
+   npm run intlayer:build
+   ```
+
+3. **如果在生产环境中使用中间件，请将 `vite-intlayer` 移动到依赖项：**
+   ```bash
+   npm install vite-intlayer --save
+   ```
+
+您的应用程序现在将支持：
+
+- **URL 结构**：`/en`、`/en/about`、`/tr`、`/tr/about`
+- **基于浏览器偏好的自动语言环境检测**
+- **基于 Tanstack Start 的语言环境感知路由**
+- **带有自动生成类型的 TypeScript 支持**
+- **具有正确语言环境处理的服务器端渲染**
+
 ## VS Code 扩展
 
-- **Intlayer VS Code 扩展** → 自动补全、错误提示、内联预览、快速操作。
-  市场链接：`intlayer.intlayer-vs-code-extension`
+为了提升您使用 Intlayer 的开发体验，您可以安装官方的 **Intlayer VS Code 扩展**。
+
+[从 VS Code 市场安装](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
+
+该扩展提供：
+
+- 翻译键的 **自动补全**。
+- 缺失翻译的 **实时错误检测**。
+- 翻译内容的 **内联预览**。
+- 轻松创建和更新翻译的 **快速操作**。
+
+有关如何使用该扩展的更多详细信息，请参阅 [Intlayer VS Code 扩展文档](https://intlayer.org/doc/vs-code-extension)。
 
 ---
 
 ## 深入了解
 
-- 可视化编辑器
-- CMS 模式
-- 边缘/适配器上的语言环境检测
+要进一步提升，您可以实现[可视化编辑器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_visual_editor.md)或使用[CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md)将内容外部化。
 
 ---
 
+## 文档参考
+
+- [Intlayer 文档](https://intlayer.org)
+- [Tanstack Start 文档](https://reactrouter.com/)
+- [useIntlayer 钩子](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/react-intlayer/useIntlayer.md)
+- [useLocale 钩子](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/react-intlayer/useLocale.md)
+- [内容声明](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/get_started.md)
+- [配置](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)
+
+本综合指南提供了将 Intlayer 与 Tanstack Start 集成所需的一切，支持完全国际化的应用程序，具备区域感知路由和 TypeScript 支持。
+
 ## 文档历史
 
-| 版本  | 日期       | 变更内容                       |
-| ----- | ---------- | ------------------------------ |
-| 1.0.0 | 2025-08-11 | 添加了 TanStack Start 适配支持 |
+| 版本  | 日期       | 变更内容               |
+| ----- | ---------- | ---------------------- |
+| 5.8.1 | 2025-09-09 | 为 Tanstack Start 添加 |