@intlayer/docs 9.0.0-canary.4 → 9.0.0-canary.6

package/docs/zh/intlayer_with_react_router_v7_fs_routes.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:
@@ -80,64 +80,6 @@ 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
-```
-
-```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)、转译以及[命令行工具](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/index.md)。
-
-- **react-intlayer**
-  将 Intlayer 集成到 React 应用中的包。它提供了 React 国际化的上下文提供者和钩子。
-
-- **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">
@@ -205,25 +147,6 @@ export default defineConfig({
 
 > `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 [
-  layout("routes/layout.tsx", [
-    route("/:lang?", "routes/page.tsx"), // 本地化主页
-    route("/:lang?/about", "routes/about/page.tsx"), // 本地化关于页面
-  ]),
-] satisfies RouteConfig;
-```
-
-### 第5步：创建布局组件
-
-设置根布局和特定语言环境的布局：
-
 #### 根布局
 
 ```tsx fileName="app/routes/layout.tsx"
@@ -243,111 +166,6 @@ export default function RootLayout({ params }: Route.ComponentProps) {
 }
 ```
 
-### 第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/[lang]/page.tsx"
@@ -373,67 +191,6 @@ export default function Page() {
 
 > 如果您的应用程序已经存在，您可以结合使用 [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 属性：
@@ -641,91 +398,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 using file-system based routing 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 支持。

package/docs/zh/intlayer_with_storybook.md

@@ -76,70 +76,6 @@ Storybook 是开发和记录 UI 组件的行业标准工具。通过将它与 In
 
 ---
 
-## 逐步设置指南
-
-<Tabs>
-<Tab value="Vite Setup">
-
-### 第一步：安装依赖项
-
-```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`       | 核心 - 配置、内容编译、命令行工具                   |
-| `react-intlayer` | React 绑定 - `IntlayerProvider`, `useIntlayer` 钩子 |
-| `vite-intlayer`  | Vite 插件 - 监听并编译内容声明文件                  |
-
----
-
-### 第二步：创建 Intlayer 配置
-
-在项目的根目录（或设计系统包内）创建 `intlayer.config.ts`：
-
-```typescript fileName="intlayer.config.ts" codeFormat="typescript"
-import { Locales, type IntlayerConfig } from "intlayer";
-
-const config: IntlayerConfig = {
-  internationalization: {
-    locales: [
-      Locales.ENGLISH,
-      Locales.FRENCH,
-      Locales.SPANISH,
-      // 根据需要添加更多语言
-    ],
-    defaultLocale: Locales.ENGLISH,
-  },
-  content: {
-    contentDir: ["./src"], // 您的 *.content.ts 文件所在位置
-  },
-};
-
-export default config;
-```
-
-> 有关完整选项列表，请参见 [配置参考](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)。
-
----
-
 ### 第三步：将 Vite 插件添加到 Storybook
 
 Storybook 的 `viteFinal` 钩子允许您扩展内部的 Vite 配置。在此处导入并添加 `intlayer()` 插件：
@@ -181,182 +117,6 @@ export default config;
 
 ---
 
-### 第四步：添加 `IntlayerProvider` 装饰器和语言工具栏
-
-Storybook 的 `preview` 文件是使用 `IntlayerProvider` 包裹每个 story，并在工具栏中暴露语言切换器的最佳场所：
-
-```tsx fileName=".storybook/preview.tsx" codeFormat="typescript"
-import type { Preview, StoryContext } from "@storybook/react";
-import { IntlayerProvider } from "react-intlayer";
-
-const preview: Preview = {
-  // 在 IntlayerProvider 中包裹每个 story
-  decorators: [
-    (Story, context: StoryContext) => {
-      const locale = context.globals.locale ?? "en";
-      return (
-        <IntlayerProvider locale={locale}>
-          <Story />
-        </IntlayerProvider>
-      );
-    },
-  ],
-
-  // 在 Storybook 工具栏中暴露语言切换器
-  globalTypes: {
-    locale: {
-      description: "当前语言",
-      defaultValue: "en",
-      toolbar: {
-        title: "语言",
-        icon: "globe",
-        items: [
-          { value: "en", title: "English" },
-          { value: "fr", title: "Français" },
-          { value: "es", title: "Español" },
-        ],
-        dynamicTitle: true,
-      },
-    },
-  },
-
-  parameters: {
-    controls: {
-      matchers: {
-        color: /(background|color)$/i,
-        date: /Date$/i,
-      },
-    },
-  },
-};
-
-export default preview;
-```
-
-> `locale` 的值必须与您在 `intlayer.config.ts` 中声明的语言一致。
-
-</Tab>
-<Tab value="Webpack Setup">
-
-### 第一步：安装依赖项
-
-```bash packageManager="npm"
-npm install intlayer react-intlayer
-npm install @intlayer/webpack --save-dev
-```
-
-```bash packageManager="pnpm"
-pnpm add intlayer react-intlayer
-pnpm add @intlayer/webpack --save-dev
-```
-
-```bash packageManager="yarn"
-yarn add intlayer react-intlayer
-yarn add @intlayer/webpack --save-dev
-```
-
-```bash packageManager="bun"
-bun add intlayer react-intlayer
-bun add @intlayer/webpack --dev
-```
-
----
-
-### 第二步：创建 Intlayer 配置
-
-在项目的根目录创建 `intlayer.config.ts`：
-
-```typescript fileName="intlayer.config.ts" codeFormat="typescript"
-import { Locales, type IntlayerConfig } from "intlayer";
-
-const config: IntlayerConfig = {
-  internationalization: {
-    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
-    defaultLocale: Locales.ENGLISH,
-  },
-  content: {
-    contentDir: ["./src"],
-  },
-};
-
-export default config;
-```
-
----
-
-### 第三步：配置 Storybook 的 Webpack
-
-对于基于 Webpack 的 Storybook 设置（例如 `@storybook/react-webpack5`），请通过 `webpackFinal` 扩展 Webpack 配置，以添加 Intlayer 别名和加载器：
-
-```typescript fileName=".storybook/main.ts" codeFormat="typescript"
-import type { StorybookConfig } from "@storybook/react-webpack5";
-import { IntlayerPlugin } from "@intlayer/webpack";
-
-const config: StorybookConfig = {
-  stories: ["../src/**/*.stories.@(js|jsx|ts|tsx)"],
-  addons: ["@storybook/addon-essentials"],
-  framework: {
-    name: "@storybook/react-webpack5",
-    options: {},
-  },
-
-  webpackFinal: async (baseConfig) => {
-    baseConfig.plugins = [...(baseConfig.plugins ?? []), new IntlayerPlugin()];
-    return baseConfig;
-  },
-};
-
-export default config;
-```
-
----
-
-### 第四步：添加 `IntlayerProvider` 装饰器和语言工具栏
-
-与 Vite 设置相同 -- 在 `.storybook/preview.tsx` 中添加装饰器和全局语言类型：
-
-```tsx fileName=".storybook/preview.tsx" codeFormat="typescript"
-import type { Preview, StoryContext } from "@storybook/react";
-import { IntlayerProvider } from "react-intlayer";
-
-const preview: Preview = {
-  decorators: [
-    (Story, context: StoryContext) => {
-      const locale = context.globals.locale ?? "en";
-      return (
-        <IntlayerProvider locale={locale}>
-          <Story />
-        </IntlayerProvider>
-      );
-    },
-  ],
-
-  globalTypes: {
-    locale: {
-      description: "当前语言",
-      defaultValue: "en",
-      toolbar: {
-        title: "语言",
-        icon: "globe",
-        items: [
-          { value: "en", title: "English" },
-          { value: "fr", title: "Français" },
-          { value: "es", title: "Español" },
-        ],
-        dynamicTitle: true,
-      },
-    },
-  },
-};
-
-export default preview;
-```
-
-</Tab>
-</Tabs>
-
----
-
 ## 声明内容
 
 在每个组件旁边创建一个 `*.content.ts` 文件。Intlayer 会在编译期间自动识别它。