@intlayer/docs 8.12.4 → 9.0.0-canary.10

package/docs/zh/intlayer_with_react_router_v7.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-09-04
-updatedAt: 2026-05-31
+updatedAt: 2026-06-23
 title: "React Router v7 i18n - 翻译你的应用的完整指南"
 description: "告别 i18next。2026 年构建多语言 (i18n) React Router v7 应用的完整指南。使用 AI 代理翻译并优化包体积、SEO 和性能。"
 keywords:
@@ -36,6 +36,7 @@ history:
   - version: 5.8.2
     date: 2025-09-04
     changes: "添加 React Router v7 支持"
+author: aymericzip
 ---
 
 # 使用Intlayer翻译您的React Router v7 | 国际化(i18n)
@@ -80,34 +81,48 @@ Intlayer 不仅仅是一个 i18n 解决方案，还提供了一个**自托管的
 
 ---
 
-## 在 React Router v7 应用中设置 Intlayer 的分步指南
-
 ### 第一步：安装依赖
 
 使用您喜欢的包管理器安装必要的包：
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> `--interactive` 标志是可选的。如果您是 AI 代理，请使用 `intlayer-cli init`。
+
+> 该命令将检测您的环境并安装所需的软件包。例如：
+
 ```bash packageManager="npm"
 npm install intlayer react-intlayer
 npm install vite-intlayer --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer react-intlayer
 pnpm add vite-intlayer --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer react-intlayer
 yarn add vite-intlayer --save-dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer react-intlayer
 bun add vite-intlayer --dev
-bun x intlayer init
 ```
 
 - **intlayer**
@@ -120,8 +135,6 @@ bun x intlayer init
 - **vite-intlayer**
   包含用于将 Intlayer 集成到 [Vite 打包工具](https://vite.dev/guide/why.html#why-bundle-for-production) 的 Vite 插件，以及用于检测用户首选语言、管理 Cookie 和处理 URL 重定向的中间件。
 
-### 第 2 步：项目配置
-
 ## 在 React Router v7 应用程序中使用基于文件系统的路由设置 Intlayer 的分步指南
 
 <Tabs defaultTab="video">
@@ -173,39 +186,6 @@ export default config;
 
 > 通过此配置文件，您可以设置本地化的 URL、中间件重定向、cookie 名称、内容声明的位置和扩展名，禁用控制台中的 Intlayer 日志等。有关可用参数的完整列表，请参阅[配置文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)。
 
-### 第三步：在您的 Vite 配置中集成 Intlayer
-
-将 intlayer 插件添加到您的配置中：
-
-```typescript fileName="vite.config.ts"
-import { reactRouter } from "@react-router/dev/vite";
-import { defineConfig } from "vite";
-import { intlayer } from "vite-intlayer";
-
-export default defineConfig({
-  plugins: [reactRouter(), intlayer()],
-});
-```
-
-> `intlayer()` Vite 插件用于将 Intlayer 集成到 Vite 中。它确保内容声明文件的构建，并在开发模式下监视这些文件。它在 Vite 应用中定义了 Intlayer 的环境变量。此外，它还提供别名以优化性能。
-
-### 第4步：配置 React Router v7 路由
-
-设置支持多语言的路由配置：
-
-```typescript fileName="app/routes.ts"
-import { layout, route, type RouteConfig } from "@react-router/dev/routes";
-
-export default [
-  route("/:lang?", "routes/page.tsx"), // 本地化主页
-  route("/:lang?/about", "routes/about/page.tsx"), // 本地化关于页面
-] satisfies RouteConfig;
-```
-
-### 第5步：创建布局组件
-
-设置根布局和特定语言环境的布局：
-
 #### 根布局
 
 ```tsx fileName="app/root.tsx"
@@ -256,222 +236,6 @@ export function Layout({
 }
 ```
 
-### 第6步：声明您的内容
-
-创建并管理您的内容声明以存储翻译：
-
-```tsx fileName="app/routes/[lang]/page.content.ts"
-import { t, type Dictionary } from "intlayer";
-
-const pageContent = {
-  key: "page",
-  content: {
-    title: t({
-      en: "Welcome to React Router v7 + Intlayer",
-      es: "Bienvenido a React Router v7 + Intlayer",
-      fr: "Bienvenue sur React Router v7 + Intlayer",
-    }),
-    description: t({
-      en: "Build multilingual applications with ease using React Router v7 and Intlayer.",
-      es: "Cree aplicaciones multilingües fácilmente usando React Router v7 y Intlayer.",
-      fr: "Créez des applications multilingues facilement avec React Router v7 et Intlayer.",
-    }),
-    aboutLink: t({
-      en: "了解我们",
-      es: "Aprender Sobre Nosotros",
-      fr: "En savoir plus sur nous",
-    }),
-    homeLink: t({
-      en: "首页",
-      es: "Inicio",
-      fr: "Accueil",
-    }),
-  },
-} satisfies Dictionary;
-
-export default pageContent;
-```
-
-> 您的内容声明可以定义在应用程序中的任何位置，只要它们被包含在 `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)。
-
-### 第7步：创建支持多语言的组件
-
-创建一个 `LocalizedLink` 组件，用于支持多语言的导航：
-
-```tsx fileName="app/components/localized-link.tsx"
-import type { FC } from "react";
-
-import { getLocalizedUrl, type LocalesValues } from "intlayer";
-import { useLocale } from "react-intlayer";
-import { Link, type LinkProps, type To } from "react-router";
-
-const isExternalLink = (to: string) => /^(https?:)?\/\//.test(to); // 判断是否为外部链接
-
-export const locacalizeTo = (to: To, locale: LocalesValues): To => {
-  if (typeof to === "string") {
-    if (isExternalLink(to)) {
-      return to; // 如果是外部链接，直接返回
-    }
-
-    return getLocalizedUrl(to, locale); // 获取本地化的URL
-  }
-
-  if (isExternalLink(to.pathname ?? "")) {
-    return to; // 如果路径名是外部链接，直接返回
-  }
-
-  return {
-    ...to,
-    pathname: getLocalizedUrl(to.pathname ?? "", locale), // 本地化路径名
-  };
-};
-
-export const LocalizedLink: FC<LinkProps> = (props) => {
-  const { locale } = useLocale(); // 获取当前语言环境
-
-  return <Link {...props} to={locacalizeTo(props.to, locale)} />;
-};
-```
-
-如果你想导航到本地化路由，可以使用 `useLocalizedNavigate` 钩子：
-
-```tsx fileName="app/hooks/useLocalizedNavigate.ts"
-import { useLocale } from "react-intlayer";
-import { type NavigateOptions, type To, useNavigate } from "react-router";
-
-import { locacalizeTo } from "~/components/localized-link";
-
-export const useLocalizedNavigate = () => {
-  const navigate = useNavigate();
-  const { locale } = useLocale();
-
-  const localizedNavigate = (to: To, options?: NavigateOptions) => {
-    const localedTo = locacalizeTo(to, locale);
-
-    navigate(localedTo, options);
-  };
-
-  return localizedNavigate;
-};
-```
-
-### 第8步：在你的页面中使用 Intlayer
-
-在您的整个应用程序中访问内容字典：
-
-#### 本地化主页
-
-```tsx fileName="app/routes/page.tsx"
-import { getIntlayer, validatePrefix } from "intlayer";
-import { useIntlayer } from "react-intlayer";
-import { data } from "react-router";
-
-import { LocaleSwitcher } from "~/components/locale-switcher";
-
-import { Navbar } from "~/components/navbar";
-import type { Route } from "./+types/page";
-
-export const loader = ({ params }: Route.LoaderArgs) => {
-  const { locale } = params;
-
-  const { isValid } = validatePrefix(locale);
-
-  if (!isValid) {
-    throw data("Locale not supported", { status: 404 });
-  }
-};
-
-export const meta: Route.MetaFunction = ({ params }) => {
-  const content = getIntlayer("page", params.locale);
-
-  return [
-    { title: content.title },
-    { content: content.description, name: "description" },
-  ];
-};
-
-export default function Page() {
-  const { title, description, aboutLink } = useIntlayer("page");
-
-  return (
-    <div>
-      <h1>{title}</h1>
-      <p>{description}</p>
-      <nav>
-        <LocalizedLink to="/about">{aboutLink}</LocalizedLink>
-      </nav>
-    </div>
-  );
-}
-```
-
-> 想了解更多关于 `useIntlayer` 钩子的内容，请参阅[文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/react-intlayer/useIntlayer.md)。
-
-> 如果您的应用程序已经存在，您可以结合使用 [Intlayer 编译器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compiler.md) 和 [提取命令](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/extract.md) 在一秒钟内转换成干个组件。
-
-### 第9步：创建语言切换组件
-
-创建一个组件，允许用户切换语言：
-
-```tsx fileName="app/components/locale-switcher.tsx"
-import type { FC } from "react";
-
-import {
-  getHTMLTextDir,
-  getLocaleName,
-  getLocalizedUrl,
-  getPathWithoutLocale,
-  Locales,
-} from "intlayer";
-import { setLocaleInStorage, useIntlayer, useLocale } from "react-intlayer";
-import { Link, useLocation } from "react-router";
-
-export const LocaleSwitcher: FC = () => {
-  const { localeSwitcherLabel } = useIntlayer("locale-switcher"); // 使用 useIntlayer 钩子获取本地化标签
-  const { pathname } = useLocation(); // 获取当前路径名
-
-  const { availableLocales, locale } = useLocale(); // 获取可用语言和当前语言
-
-  const pathWithoutLocale = getPathWithoutLocale(pathname); // 获取不带语言前缀的路径
-
-  return (
-    <ol>
-      {availableLocales.map((localeItem) => (
-        <li key={localeItem}>
-          <Link
-            aria-current={localeItem === locale ? "page" : undefined}
-            aria-label={`${localeSwitcherLabel.value} ${getLocaleName(localeItem)}`}
-            onClick={() => setLocale(localeItem)}
-            to={getLocalizedUrl(pathWithoutLocale, localeItem)}
-          >
-            <span>
-              {/* 语言环境 - 例如 FR */}
-              {localeItem}
-            </span>
-            <span>
-              {/* 语言在其自身语言环境中的名称 - 例如 Français */}
-              {getLocaleName(localeItem, locale)}
-            </span>
-            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
-              {/* 语言在当前语言环境中的名称 - 例如当前语言环境为 Locales.SPANISH 时显示 Francés */}
-              {getLocaleName(localeItem)}
-            </span>
-            <span dir="ltr" lang={Locales.ENGLISH}>
-              {/* 语言的英文名称 - 例如 French */}
-              {getLocaleName(localeItem, Locales.ENGLISH)}
-            </span>
-          </Link>
-        </li>
-      ))}
-    </ol>
-  );
-};
-```
-
-> 想了解更多关于 `useLocale` 钩子的内容，请参阅[文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/react-intlayer/useLocale.md)。
-
 ### 第10步：添加HTML属性管理（可选）
 
 创建一个钩子来管理HTML的 lang 和 dir 属性：
@@ -575,6 +339,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel 编译器'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 更新您的 `vite.config.ts` 以包含 `intlayerCompiler` 插件：
 
 ```ts fileName="vite.config.ts"
@@ -584,7 +350,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 添加编译器插件
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```
@@ -678,91 +444,3 @@ To go further, you can implement the [visual editor](https://github.com/aymericz
 - [Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)
 
 This comprehensive guide provides everything you need to integrate Intlayer with React Router v7 for a fully internationalized application with locale-aware routing and TypeScript support.
-
-### 第11步：添加中间件（可选）
-
-你也可以使用 `intlayerProxy` 为你的应用添加服务器端路由。该插件会根据 URL 自动检测当前的语言环境，并设置相应的语言环境 cookie。如果未指定语言环境，插件将根据用户浏览器的语言偏好确定最合适的语言环境。如果仍未检测到语言环境，则会重定向到默认语言环境。
-
-> 注意，要在生产环境中使用 `intlayerProxy`，你需要将 `vite-intlayer` 包从 `devDependencies` 切换到 `dependencies`。
-
-```typescript {3,7} fileName="vite.config.ts"
-import { reactRouter } from "@react-router/dev/vite";
-import { defineConfig } from "vite";
-import { intlayer, intlayerProxy } from "vite-intlayer";
-
-export default defineConfig({
-  plugins: [
-    intlayerProxy(), // should be placed first
-    reactRouter(),
-
-    intlayer(),
-  ],
-});
-```
-
----
-
-## 配置 TypeScript
-
-Intlayer 使用模块增强来利用 TypeScript 的优势，使您的代码库更强大。
-
-确保您的 TypeScript 配置包含自动生成的类型：
-
-```json5 fileName="tsconfig.json"
-{
-  // ... 您现有的配置
-  include: [
-    // ... 您现有的包含项
-    ".intlayer/**/*.ts", // 包含自动生成的类型
-  ],
-}
-```
-
----
-
-## Git 配置
-
-建议忽略 Intlayer 生成的文件，这样可以避免将它们提交到您的 Git 仓库。
-
-为此，您可以在 `.gitignore` 文件中添加以下指令：
-
-```plaintext fileName=".gitignore"
-# 忽略 Intlayer 生成的文件
-.intlayer
-```
-
----
-
-## VS Code 扩展
-
-为了提升您使用 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)。
-
----
-
-## 深入了解
-
-要更进一步，您可以实现[可视化编辑器](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)
-- [React Router v7 文档](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/content_file.md)
-- [配置](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)
-
-本综合指南提供了将 Intlayer 与 React Router v7 集成所需的一切，支持完全国际化的应用程序，具备基于区域设置的路由和 TypeScript 支持。