使用 Intlayer 翻译您的 React Router v7 网站

本指南演示了如何在 React Router v7 项目中集成 Intlayer，实现无缝国际化，支持基于语言环境的路由、TypeScript 支持以及现代开发实践。

本指南同时涵盖基于配置的路由（routes.ts）和基于文件系统的路由（@react-router/fs-routes）。

目录

为什么选择 Intlayer 而不是其他方案？

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

在 React Router v7 应用中设置 Intlayer 的分步指南

See the Config-Based Routing Template or File-System Routes Template on GitHub.

1. 1

   安装依赖

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

   bash

   复制内容

   复制代码

   复制代码到剪贴板

   npx intlayer init --interactive
   

   --interactive 标志是可选的。如果您是 AI agent，请使用 intlayer-cli init。

   此命令将检测您的环境并安装所需的包。例如：

   bash

   复制内容

   复制代码

   复制代码到剪贴板

   npm install intlayer react-intlayer
   npm install vite-intlayer --save-dev
   

   • intlayer

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

   • react-intlayer 将 Intlayer 与 React 应用集成的包。它为 React 国际化提供了上下文 Provider 和 Hook。

   • vite-intlayer 包括用于将 Intlayer 与 Vite bundler 集成的 Vite 插件，以及用于检测用户首选区域设置、管理 cookie 和处理 URL 重定向的中间件。

2. 2

   配置您的项目

   Config-based routingFile-system routes

   架构

   在此架构中，路由在 app/routes.ts 中以编程方式定义，并带有可选的 /:locale? 动态段。本地化页面、布局和内容声明都组织在 app/ 目录下：

   bash

   复制内容

   复制代码

   复制代码到剪贴板

   .
   ├── app
   │   ├── components
   │   │   ├── locale-switcher.content.ts
   │   │   ├── locale-switcher.tsx
   │   │   ├── localized-link.tsx
   │   │   ├── navbar.content.ts
   │   │   └── navbar.tsx
   │   ├── hooks
   │   │   ├── useI18nHTMLAttributes.tsx
   │   │   └── useLocalizedNavigate.tsx
   │   ├── routes
   │   │   ├── about
   │   │   │   ├── page.content.ts
   │   │   │   └── page.tsx
   │   │   ├── layout.tsx
   │   │   ├── page.content.ts
   │   │   └── page.tsx
   │   ├── root.tsx                      # Root layout for IntlayerProvider
   │   └── routes.ts                     # Route definition file
   ├── intlayer.config.ts
   ├── package.json
   ├── react-router.config.ts
   ├── tsconfig.json
   └── vite.config.ts
   

   配置

   创建 intlayer.config.ts 配置文件以声明应用程序支持的语言：

   intlayer.config.ts

   复制内容

   复制代码

   复制代码到剪贴板

   import { type IntlayerConfig, Locales } from "intlayer";
   
   const config: IntlayerConfig = {
     internationalization: {
       defaultLocale: Locales.ENGLISH,
       locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
     },
   };
   
   export default config;
   

   架构

   在此架构中，路由遵循使用 flatRoutes 的 React Router v7 文件系统路由规范，其中点（.）代表 URL 段，($locale) 表示可选的本地化段：

   bash

   复制内容

   复制代码

   复制代码到剪贴板

   .
   ├── app
   │   ├── components
   │   │   ├── locale-switcher.content.ts
   │   │   ├── locale-switcher.tsx
   │   │   ├── localized-link.tsx
   │   │   ├── navbar.content.ts
   │   │   └── navbar.tsx
   │   ├── hooks
   │   │   ├── useI18nHTMLAttributes.tsx
   │   │   └── useLocalizedNavigate.tsx
   │   ├── routes
   │   │   ├── ($locale)._index.content.ts
   │   │   ├── ($locale)._index.tsx
   │   │   ├── ($locale).about.content.ts
   │   │   └── ($locale).about.tsx
   │   ├── root.tsx                      # Root layout for IntlayerProvider
   │   └── routes.ts                     # Route definition file using flatRoutes
   ├── intlayer.config.ts
   ├── package.json
   ├── react-router.config.ts
   ├── tsconfig.json
   └── vite.config.ts
   

   配置

   创建 intlayer.config.ts 配置文件以声明应用程序支持的语言：

   intlayer.config.ts

   复制内容

   复制代码

   复制代码到剪贴板

   import { type IntlayerConfig, Locales } from "intlayer";
   
   const config: IntlayerConfig = {
     internationalization: {
       defaultLocale: Locales.ENGLISH,
       locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
     },
   };
   
   export default config;
   

   通过此配置文件，您可以设置本地化的 URL、中间件重定向、cookie 名称、内容声明的位置和扩展名，禁用控制台中的 Intlayer 日志等。有关可用参数的完整列表，请参阅配置文档。

   配置文档
3. 3

   在您的 Vite 配置中集成 Intlayer

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

   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. 4

   配置 React Router v7 Routes

   Config-based routingFile-system routes

   使用本地化感知路由设置您的路由配置：

   app/routes.ts

   复制内容

   复制代码

   复制代码到剪贴板

   import { layout, route, type RouteConfig } from "@react-router/dev/routes";
   
   export default [
     route("/:locale?", "routes/page.tsx"), // 本地化主页
     route("/:locale?/about", "routes/about/page.tsx"), // 本地化关于页面
   ] satisfies RouteConfig;
   

   Set up your routing configuration to use file-system based routes with flatRoutes:

   app/routes.ts

   复制内容

   复制代码

   复制代码到剪贴板

   import type { RouteConfig } from "@react-router/dev/routes";
   import { flatRoutes } from "@react-router/fs-routes";
   import { configuration } from "intlayer";
   
   const routes: RouteConfig = flatRoutes({
     // Ignore content declaration files from being treated as routes
     ignoredRouteFiles: configuration.content.fileExtensions.map(
       (fileExtension) => `**/*${fileExtension}`
     ),
   });
   
   export default routes;
   

   The flatRoutes function from @react-router/fs-routes enables file-system based routing, where the file structure in the routes/ directory determines your application's routes. The ignoredRouteFiles option ensures that Intlayer content declaration files (.content.ts, etc.) are not treated as route files.

5. 5

   创建根布局

   设置您的根布局和特定于语言的布局：

   根布局

   app/root.tsx

   复制内容

   复制代码

   复制代码到剪贴板

   import { getLocaleFromPath } from "intlayer";
   import { IntlayerProvider } from "react-intlayer";
   import {
     data,
     Meta,
     Scripts,
     ScrollRestoration,
     useLoaderData,
   } from "react-router";
   import type { Route } from "./+types/root";
   
   // ... Unchanged App, links and ErrorBoundary code
   
   export async function loader({ request }: Route.LoaderArgs) {
     const locale = getLocaleFromPath(request.url);
   
     if (!locale) {
       throw data("Language not supported", { status: 404 });
     }
   
     return { locale };
   }
   
   export function Layout({
     children,
   }: { children: React.ReactNode } & Route.ComponentProps) {
     const data = useLoaderData<typeof loader>();
     const { locale } = data ?? {};
   
     return (
       <html lang={locale}>
         <head>
           <meta charSet="utf-8" />
           <meta content="width=device-width, initial-scale=1" name="viewport" />
           <Meta />
           <Links />
         </head>
         <body>
           <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
           <ScrollRestoration />
           <Scripts />
         </body>
       </html>
     );
   }
   

6. 6

   声明您的内容

   创建并管理您的内容声明以存储翻译：

   app/routes/[lang]/page.content.ts

   复制内容

   复制代码

   复制代码到剪贴板

   import { t, type Dictionary } from "intlayer";
   
   const pageContent = {
     key: "page",
     content: {
       title: t({
         zh: "欢迎来到 React Router v7 + Intlayer",
         en: "Welcome to React Router v7 + Intlayer",
         es: "Bienvenido a React Router v7 + Intlayer",
         fr: "Bienvenue sur React Router v7 + Intlayer",
       }),
       description: t({
         zh: "使用 React Router v7 和 Intlayer 轻松构建多语言应用程序。",
         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({
         zh: "了解我们",
         en: "Learn About Us",
         es: "Aprender Sobre Nosotros",
         fr: "En savoir plus sur nous",
       }),
       homeLink: t({
         zh: "首页",
         en: "Home",
         es: "Inicio",
         fr: "Accueil",
       }),
     },
   } satisfies Dictionary;
   
   export default pageContent;
   

   您的内容声明可以在应用程序的任何地方定义，只要它们被包含在 contentDir 目录中（默认为 ./app）。并且匹配内容声明文件扩展名（默认为 .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}）。

   如果使用基于文件系统的路由，可以放置在 app/routes/($locale)._index.content.ts。

   有关更多详细信息，请参阅content 声明文档。

   content 声明文档
7. 7

   创建本地化感知的组件

   为区域感知导航创建一个 LocalizedLink 组件：

   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);
     }
   
     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 hook：

   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. 8

   在你的页面中使用 Intlayer

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

   本地化主页

   Config-based routingFile-system routes

   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>
     );
   }
   

   app/routes/($locale)._index.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/($locale)._index";
   
   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 hook 的信息，请参考文档。

   useIntlayer Hook 文档 | react-intlayer

   如果你的应用已经存在，你可以使用 Intlayer 编译器以及提取命令，在一秒内转换数千个组件。

   Intlayer 编译器

   提取命令
9. 9

   创建语言切换器组件

   创建一个组件以允许用户更改语言：

   Config-based routingFile-system routes

   app/components/locale-switcher.tsx

   复制内容

   复制代码

   复制代码到剪贴板

   import type { FC } from "react";
   
   import {
     getHTMLTextDir,
     getLocaleName,
     getLocalizedUrl,
     getPathWithoutLocale,
   } from "intlayer";
   import { useIntlayer, useLocale } from "react-intlayer";
   import { Link, useLocation } from "react-router";
   
   export const LocaleSwitcher: FC = () => {
     const { localeSwitcherLabel } = useIntlayer("locale-switcher");
     const { pathname } = useLocation();
   
     const { availableLocales, locale, setLocale } = 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)}
               reloadDocument // Reload the page to apply the new locale
               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={defaultLocale}>
                 {/* 用英文表示的语言 - 例如 French */}
                 {getLocaleName(localeItem, defaultLocale)}
               </span>
             </Link>
           </li>
         ))}
       </ol>
     );
   };
   

   app/components/locale-switcher.tsx

   复制内容

   复制代码

   复制代码到剪贴板

   import type { FC } from "react";
   
   import {
     getHTMLTextDir,
     getLocaleName,
     getLocalizedUrl,
     getPathWithoutLocale,
     defaultLocale,
   } from "intlayer";
   import { useIntlayer, useLocale } from "react-intlayer";
   import { Link, useLocation } from "react-router";
   
   export const LocaleSwitcher: FC = () => {
     const { localeSwitcherLabel } = useIntlayer("locale-switcher");
     const { pathname } = useLocation();
   
     const { availableLocales, locale, setLocale } = 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)}
               reloadDocument // Reload the page to apply the new locale
               to={getLocalizedUrl(pathWithoutLocale, localeItem)}
             >
               <span>
                 {/* Locale - e.g. FR */}
                 {localeItem}
               </span>
               <span>
                 {/* Language in its own Locale - e.g. Français */}
                 {getLocaleName(localeItem, locale)}
               </span>
               <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
                 {/* Language in current Locale - e.g. Francés with current locale set to Locales.SPANISH */}
                 {getLocaleName(localeItem)}
               </span>
               <span dir="ltr" lang={defaultLocale}>
                 {/* Language in English - e.g. French */}
                 {getLocaleName(localeItem, defaultLocale)}
               </span>
             </Link>
           </li>
         ))}
       </ol>
     );
   };
   

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

   useLocale Hook 文档 | react-intlayer
10. 10

    添加 HTML 属性管理

    创建一个 hook 来管理 HTML lang 和 dir 属性：

    app/hooks/useI18nHTMLAttributes.tsx

    复制内容

    复制代码

    复制代码到剪贴板

    import { getHTMLTextDir } from "intlayer";
    import { useEffect } from "react";
    import { useLocale } from "react-intlayer";
    
    export const useI18nHTMLAttributes = () => {
      const { locale } = useLocale();
    
      useEffect(() => {
        document.documentElement.lang = locale;
        document.documentElement.dir = getHTMLTextDir(locale);
      }, [locale]);
    };
    

    然后在你的根组件中使用它：

    app/routes/layout.tsx

    复制内容

    复制代码

    复制代码到剪贴板

    import { Outlet } from "react-router";
    import { IntlayerProvider } from "react-intlayer";
    
    import { useI18nHTMLAttributes } from "app/hooks/useI18nHTMLAttributes"; // 导入 hook
    
    export default function RootLayout() {
      useI18nHTMLAttributes(); // 调用 hook
    
      return (
        <IntlayerProvider>
          <Outlet />
        </IntlayerProvider>
      );
    }
    

11. 11

    添加中间件

    你也可以使用 intlayerProxy 来为你的应用添加服务器端路由。这个插件将自动根据 URL 检测当前语言环境并设置适当的语言 cookie。如果未指定语言环境，该插件将根据用户的浏览器语言偏好确定最合适的语言环境。如果未检测到语言环境，它将重定向到默认语言环境。

    注意，要在生产环境中使用 intlayerProxy，你需要将 vite-intlayer 包从 devDependencies 切换到 dependencies。

    自 Intlayer v9 起，intlayerProxy() 直接内置在 intlayer() 插件中，并通过 routing.enableProxy 选项（默认为 true）默认启用。如下所示单独注册它现在是可选的，它保留用于向后兼容性和需要控制插件顺序的设置。设置 routing.enableProxy: false 以选择退出。查看 v9 发布说明。

    v9 发布说明

    vite.config.ts

    复制内容

    复制代码

    复制代码到剪贴板

    import { defineConfig } from "vite";
    import react from "@vitejs/plugin-react-swc";
    import { intlayer } from "vite-intlayer";
    
    // https://vitejs.dev/config/
    export default defineConfig({
      plugins: [
        react(),
        intlayer({
          proxy: {
            ignore: (req) => req.url?.startsWith("/api"),
          },
        }),
      ],
    });
    

12. 12

    提取组件的内容

    可选

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

    为了简化这个过程，Intlayer 提供了一个编译器 / 提取器来转换你的组件并提取内容。

    编译器

    提取器

    要进行设置，你可以在 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;
    

    提取命令Babel 编译器

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

    bash

    复制内容

    复制代码

    复制代码到剪贴板

    npx intlayer extract
    

    intlayer >= 9intlayer < 9

    自 v9 起，intlayerCompiler 已包含在 intlayer 插件中。因此你不需要手动添加它。

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

    vite.config.ts

    复制内容

    复制代码

    复制代码到剪贴板

    import { defineConfig } from "vite";
    import { intlayer, intlayerCompiler } from "vite-intlayer";
    
    export default defineConfig({
      plugins: [
        intlayer(),
        intlayerCompiler(), // 添加编译器插件
      ],
    });
    

    构建你的应用程序来转换你的组件并提取内容

    bash

    复制内容

    复制代码

    复制代码到剪贴板

    npm run build # 或 npm run dev
    

Configure TypeScript

Intlayer uses module augmentation to get benefits of TypeScript and make your codebase stronger.

Ensure your TypeScript configuration includes the autogenerated types:

{
  // ... your existing configurations
  include: [
    // ... your existing includes
    ".intlayer/**/*.ts", // Include the auto-generated types
  ],
}

Git 配置

建议忽略 Intlayer 自动生成的文件，避免将它们提交到 Git 仓库中。

为此，您可以将以下规则添加到 .gitignore 文件中：

# 忽略 Intlayer 生成的文件
.intlayer

VS Code 插件

为了提升使用 Intlayer 的开发体验，您可以安装官方的 Intlayer VS Code 插件。

该插件提供以下特性：

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

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

深入了解

要深入了解，您可以实现 可视化编辑器 或使用 CMS 将内容外部化。

文档参考

本综合指南提供了将 Intlayer 与 React Router v7 集成所需的全部内容，帮助您构建具备支持语言环境的路由与 TypeScript 支持的完整国际化应用。

常见问题