使用Intlayer翻译您的React Router v7 | 国际化(i18n)

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

本指南重点关注前端路由。对于 fs-routes 路由，请参考 Intlayer with React Router v7 File-System Routes 指南。

目录

为什么选择 Inlayer 而不是替代品？

与 react-i18next 或 i18next 等主要解决方案相比，Intlayer 是一个具有集成优化的解决方案，例如：

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

视频代码 (基于配置)代码 (基于文件系统的路由)演示 (基于配置)

www.youtube.com

Open embedded page in fullscreen

ide.intlayer.org

Open embedded page in fullscreen

ide.intlayer.org

Open embedded page in fullscreen

intlayer-react-router-v7.vercel.app

Open embedded page in fullscreen

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 国际化提供了上下文提供者和钩子。

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

2. 2

   配置您的项目

   创建一个配置文件来配置您的应用程序语言：

   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 声明文档。

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 的信息，请参考文档。

   如果你的应用已经存在，你可以使用 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 的信息，请参考文档。

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 发布说明。

    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
    

    自 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 Configuration

It is recommended to ignore the files generated by Intlayer. This allows you to avoid committing them to your Git repository.

To do this, you can add the following instructions to your .gitignore file:

# 忽略 Intlayer 生成的文件
.intlayer

VS Code Extension

To improve your development experience with Intlayer, you can install the official Intlayer VS Code Extension.

Install from the VS Code Marketplace

This extension provides:

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

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

深入了解

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

文档参考

• Intlayer 文档
• React Router v7 文档
• useIntlayer Hook
• useLocale Hook
• 内容声明
• 配置指南

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

常见问题