Переведите ваш React Router v7 с Intlayer | Интернационализация (i18n)

Это руководство демонстрирует, как интегрировать Intlayer для бесшовной интернационализации в проектах на React Router v7 с маршрутизацией, учитывающей локаль, поддержкой TypeScript и современными практиками разработки.

Это руководство сосредоточено на фронтенд-маршрутизации. Для маршрутизации fs-routes обратитесь к руководству Intlayer с React Router v7 File-System Routes.

Table of Contents

Почему Intlayer лучше альтернатив?

По сравнению с основными решениями, такими как «react-i18next» или «i18next», Intlayer — это решение, которое включает в себя встроенные оптимизации, такие как:

Пошаговое руководство по настройке Intlayer в приложении React Router v7

VideoКод (на основе конфигурации)Код (маршруты на основе файловой системы)Демо (на основе конфигурации)

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 не является обязательным. Используйте intlayer-cli init, если вы являетесь ИИ-агентом.

   Эта команда определит вашу среду и установит необходимые пакеты. Например:

   bash

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

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

   • intlayer

     Основной пакет, предоставляющий инструменты интернационализации для управления конфигурацией, перевода, объявления контента, транспиляции и CLI-команд.

   • react-intlayer Пакет, который интегрирует Intlayer с приложением React. Он предоставляет провайдеры контекста и хуки для интернационализации в React.

   • vite-intlayer Включает плагин Vite для интеграции Intlayer с сборщиком Vite, а также промежуточное ПО для определения предпочтительной локали пользователя, управления куки и обработки перенаправления 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-адреса, перенаправления в middleware, имена cookie, расположение и расширение ваших деклараций контента, отключить логи Intlayer в консоли и многое другое. Для полного списка доступных параметров обратитесь к документации по конфигурации.

3. 3

   Интеграция Intlayer в вашу конфигурацию Vite

   Добавьте плагин 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()],
   });
   

   Плагин Vite intlayer() используется для интеграции Intlayer с Vite. Он обеспечивает сборку файлов деклараций контента и отслеживает их в режиме разработки. Определяет переменные окружения Intlayer внутри приложения Vite. Кроме того, предоставляет алиасы для оптимизации производительности.

4. 4

   Настройка маршрутов React Router v7

   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

   Создайте компоненты Layout

   Настройте корневой layout и layout для конкретных локалей:

   Корневой Layout

   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({
         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}).

   Could be placed in app/routes/($locale)._index.content.ts in case of using file-system based routing.

   Для получения дополнительной информации обратитесь к документации по объявлениям контента.

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:

   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, обратитесь к документации.

   Если ваше приложение уже существует, вы можете использовать Intlayer Compiler в сочетании с командой extract, чтобы преобразовать тысячи компонентов за одну секунду.

9. 9

   Создайте компонент переключателя локали

   Создайте компонент, позволяющий пользователям менять язык:

   Config-based routingFile-system routes

   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>
                 {/* Локаль - например, FR */}
                 {localeItem}
               </span>
               <span>
                 {/* Язык на его собственной локали - например, Français */}
                 {getLocaleName(localeItem, locale)}
               </span>
               <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
                 {/* Язык на текущей локали - например, Francés при установленной локали Locales.SPANISH */}
                 {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, обратитесь к документации.

10. 10

    Добавление управления атрибутами HTML

    Создайте хук для управления атрибутами lang и dir в HTML:

    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"; // импорт хука
    
    export default function RootLayout() {
      useI18nHTMLAttributes(); // вызов хука
    
      return (
        <IntlayerProvider>
          <Outlet />
        </IntlayerProvider>
      );
    }
    

11. 11

    Добавить middleware

    Вы также можете использовать intlayerProxy для добавления маршрутизации на стороне сервера в ваше приложение. Этот плагин автоматически определит текущую локаль на основе URL и установит соответствующую куку локали. Если локаль не указана, плагин определит наиболее подходящую локаль на основе предпочтений языка браузера пользователя. Если локаль не обнаружена, он перенаправит на локаль по умолчанию.

    Обратите внимание, что для использования intlayerProxy в production, вам необходимо переместить пакет 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 предлагает компилятор / экстрактор для преобразования ваших компонентов и извлечения содержимого.

    Чтобы настроить его, вы можете добавить раздел compiler в ваш файл intlayer.config.ts:

    intlayer.config.ts

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

    import { type IntlayerConfig } from "intlayer";
    
    const config: IntlayerConfig = {
      // ... Остальная часть вашей конфигурации
      compiler: {
        /**
         * Указывает, должен ли быть включен компилятор.
         */
        enabled: true,
    
        /**
         * Определяет путь к выходным файлам
         */
        output: ({ fileName, extension }) => `./${fileName}${extension}`,
    
        /**
         * Указывает, должны ли компоненты сохраняться после преобразования. Таким образом, компилятор можно запустить только один раз для преобразования приложения, а затем удалить.
         */
        saveComponents: false,
    
        /**
         * Префикс ключа словаря
         */
        dictionaryKeyPrefix: "",
      },
    };
    
    export default config;
    

    Команда извлеченияКомпилятор Babel

    Запустите экстрактор для преобразования компонентов и извлечения содержимого

    bash

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

    npx intlayer extract
    

    Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

    Обновите ваш vite.config.ts, чтобы включить плагин intlayerCompiler:

    vite.config.ts

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

    import { defineConfig } from "vite";
    import { intlayer, intlayerCompiler } from "vite-intlayer";
    
    export default defineConfig({
      plugins: [
        intlayer(),
        intlayerCompiler(), // Adds the compiler plugin
      ],
    });
    

    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:

# Ignore the files generated by 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:

• Autocompletion for translation keys.
• Real-time error detection for missing translations.
• Inline previews of translated content.
• Quick actions to easily create and update translations.

For more details on how to use the extension, refer to the Intlayer VS Code Extension documentation.

Go Further

To go further, you can implement the visual editor or externalize your content using the CMS.

Ссылки на документацию

• Документация Intlayer
• Документация React Router v7
• Хук useIntlayer
• Хук useLocale
• Объявление контента
• Конфигурация

Это подробное руководство содержит все необходимое для интеграции Intlayer с React Router v7 для полностью интернационализированного приложения с маршрутизацией, учитывающей локаль, и поддержкой TypeScript.

Часто задаваемые вопросы