Creation:2025-08-23Last update:2026-05-31

    Перекладіть ваш вебсайт Create React App за допомогою Intlayer | Інтернаціоналізація (i18n)

    ide.intlayer.org

    Дивіться шаблон додатку на GitHub.

    Що таке Intlayer?

    Intlayer, інноваційна open-source бібліотека для інтернаціоналізації (i18n), розроблена, щоб спростити багатомовну підтримку в сучасних веб-застосунках.

    За допомогою Intlayer ви можете:

    • Легко керуйте перекладами за допомогою декларативних словників на рівні компонентів.
    • Динамічно локалізуйте метадані, маршрути та контент.
    • Забезпечте підтримку TypeScript за допомогою автогенерованих типів, що покращують автодоповнення та виявлення помилок.
    • Отримайте переваги від розширених можливостей, таких як динамічне визначення та перемикання локалі.

    Покроковий посібник з налаштування Intlayer у React-додатку

    1. Встановіть залежності

      Встановіть необхідні пакети за допомогою npm:

      bash
      npm install intlayer react-intlayer react-scripts-intlayernpx intlayer init

      • intlayer

        The core package that provides internationalization tools for configuration management, translation, content declaration, transpilation, and CLI commands.

      • react-intlayer

        The package that integrates Intlayer with React application. It provides context providers and hooks for React internationalization.

      • react-scripts-intlayer

      Містить команди та плагіни react-scripts-intlayer для інтеграції Intlayer у застосунок на базі Create React App. Ці плагіни базуються на craco і включають додаткову конфігурацію для бандлера Webpack.

    2. Налаштування вашого проекту

      Створіть файл конфігурації для налаштування мов вашого застосунку:

      intlayer.config.ts
      import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Інші ваші локалі
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;
      За допомогою цього файлу конфігурації ви можете налаштувати локалізовані URL-адреси, перенаправлення через middleware, імена cookie, розташування та розширення ваших декларацій контенту, вимкнути логи Intlayer у консолі та інше. Для повного переліку доступних параметрів зверніться до документації з конфігурації.

    3. Інтегруйте Intlayer у конфігурацію CRA

      Змініть ваші скрипти, щоб використовувати react-intlayer

      package.json
        "scripts": {    "build": "react-scripts-intlayer build",    "start": "react-scripts-intlayer start",    "transpile": "intlayer build"  },
      react-scripts-intlayer scripts are based on CRACO. You can also implement your own setup based on the intlayer craco plugin. See example here.

    4. Оголосіть свій вміст

      Create and manage your content declarations to store translations:

      src/app.content.tsx
      import { t, type Dictionary } from "intlayer";
import React, { type ReactNode } from "react";

const appContent = {
  key: "app",
  content: {
    getStarted: t<ReactNode>({
      uk: (
        <>
          Відредагуйте <code>src/App.tsx</code> та збережіть, щоб
          перезавантажити
        </>
      ),
      en: (
        <>
          Edit <code>src/App.tsx</code> and save to reload
        </>
      ),
      fr: (
        <>
          Éditez <code>src/App.tsx</code> et enregistrez pour recharger
        </>
      ),
      uk: (
        <>
          Редагуйте <code>src/App.tsx</code> і збережіть, щоб перезавантажити
        </>
      ),
      es: (
        <>
          Edita <code>src/App.tsx</code> y guarda para recargar
        </>
      ),
    }),
    reactLink: {
      href: "https://reactjs.org",
      content: t({
        uk: "Вивчити React",
        en: "Learn React",
        fr: "Apprendre React",
        es: "Aprender React",
      }),
    },
  },
} satisfies Dictionary;

export default appContent;
      Ваші декларації контенту можуть бути визначені в будь-якому місці вашого застосунку, якщо вони включені до директорії contentDir (за замовчуванням, ./src). І вони повинні відповідати розширенню файлу декларації контенту (за замовчуванням, .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).
      Для отримання детальнішої інформації зверніться до документації щодо декларації контенту.
      Якщо ваш файл контенту містить код TSX, слід розглянути імпорт import React from "react"; у вашому файлі контенту.

    5. Використання Intlayer у вашому коді

      Отримуйте доступ до словників контенту у всьому застосунку:

      src/App.tsx
      import logo from "./logo.svg";
import "./App.css";
import type { FC } from "react";
import { IntlayerProvider, useIntlayer } from "react-intlayer";

const AppContent: FC = () => {
  const content = useIntlayer("app");

  return (
    <div className="App">
      <img src={logo} className="App-logo" alt="логотип" />

      {content.getStarted}
      <a
        className="App-link"
        href={content.reactLink.href.value}
        target="_blank"
        rel="noopener noreferrer"
      >
        {content.reactLink.content}
      </a>
    </div>
  );
};

const App: FC = () => (
  <IntlayerProvider>
    <AppContent />
  </IntlayerProvider>
);

export default App;
      Примітка: Якщо ви хочете використовувати ваш контент у string атрибуті, наприклад alt, title, href, aria-label тощо, ви повинні викликати значення функції, як-от:
      html
      <img src="{content.image.src.value}" alt="{content.image.value}" /><img src="{content.image.src.toString()}" alt="{content.image.toString()}" /><img src="{String(content.image.src)}" alt="{String(content.image)}" />
      Щоб дізнатися більше про хук useIntlayer, перегляньте документацію.

    6. Зміна мови вашого контенту

      Необов'язково

      Щоб змінити мову контенту, ви можете використати функцію setLocale, що надається хуком useLocale. Ця функція дозволяє встановити locale застосунку та відповідно оновити контент.

      src/components/LocaleSwitcher.tsx
      import { Locales } from "intlayer";
import { useLocale } from "react-intlayer";

const LocaleSwitcher = () => {
  const { setLocale } = useLocale();

  return (
    <button onClick={() => setLocale(Locales.English)}>
      Change Language to English
    </button>
  );
};
      Щоб дізнатися більше про хук useLocale, зверніться до документації.

    7. Додайте локалізовану маршрутизацію до вашого додатку

      Необов'язково

      Мета цього кроку, створити унікальні маршрути для кожної мови. Це корисно для SEO та SEO-дружніх URL-адрес. Приклад:

      plaintext
      - https://example.com/about- https://example.com/es/about- https://example.com/fr/about
      За замовчуванням маршрути не мають префікса для локалі за замовчуванням. Якщо ви хочете додати префікс і для локалі за замовчуванням, встановіть опцію middleware.prefixDefault в true у вашій конфігурації. Див. документацію з конфігурації для докладнішої інформації.

      Щоб додати локалізовану маршрутизацію у ваш застосунок, можна створити компонент LocaleRouter, який обгортає маршрути вашого застосунку й обробляє маршрутизацію на основі локалі. Ось приклад з використанням React Router:

      src/components/LocaleRouter.tsx
      // Імпорт необхідних залежностей та функцій
import { type Locales, configuration, getPathWithoutLocale } from "intlayer"; // Утиліти та типи з 'intlayer'
// Утиліти та типи з 'intlayer'
import type { FC, PropsWithChildren } from "react"; // Типи React для функціональних компонентів та пропсів
import { IntlayerProvider } from "react-intlayer"; // Провайдер контексту інтернаціоналізації
import {
  BrowserRouter,
  Routes,
  Route,
  Navigate,
  useLocation,
} from "react-router-dom"; // Компоненти роутера для керування навігацією

// Деструктуризація конфігурації з Intlayer
const { internationalization, middleware } = configuration;
const { locales, defaultLocale } = internationalization;

/**
 * Компонент, що обробляє локалізацію та обгортає дочірні елементи у відповідний контекст локалі.
 */
 * Виконує визначення та перевірку локалі на основі URL.
 */
const AppLocalized: FC<PropsWithChildren<{ locale: Locales }>> = ({
  children,
  locale,
}) => {
  const { pathname, search } = useLocation(); // Отримати поточний шлях URL

  // Визначає поточну локаль, за відсутності значення використовується локаль за замовчуванням
  const currentLocale = locale ?? defaultLocale;

  // Видаляє префікс локалі з шляху для побудови базового шляху
  const pathWithoutLocale = getPathWithoutLocale(
    pathname // Поточний шлях URL
  );

  /**
   * Якщо middleware.prefixDefault дорівнює true, локаль за замовчуванням завжди повинна мати префікс.
   */
  if (middleware.prefixDefault) {
    // Перевірити локаль
    if (!locale || !locales.includes(locale)) {
      // Перенаправити на локаль за замовчуванням зі оновленим шляхом
      return (
        <Navigate
          to={`/${defaultLocale}/${pathWithoutLocale}${search}`}
          replace // Замінити поточний запис історії на новий
        />
      );
    }

    // Огорнути дочірні елементи IntlayerProvider та встановити поточну локаль
    return (
      <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
    );
  } else {
    /**
     * Коли middleware.prefixDefault дорівнює false, за замовчуванням локаль не має префікса.
     * Переконайтеся, що поточна локаль є дійсною і не є локаллю за замовчуванням.
     */
    if (
      currentLocale.toString() !== defaultLocale.toString() &&
      !locales
        .filter(
          (locale) => locale.toString() !== defaultLocale.toString() // Виключити локаль за замовчуванням
        )
        .includes(currentLocale) // Перевіряє, чи поточна локаль входить до списку дійсних локалей
    ) {
      // Перенаправляє на шлях без префікса локалі
      return <Navigate to={`${pathWithoutLocale}${search}`} replace />;
    }

    // Обгортає дочірні елементи IntlayerProvider та встановлює поточну локаль
    return (
      <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
    );
  }
};

/**
 * Компонент маршрутизатора, який налаштовує маршрути, специфічні для локалі.
 * Використовує React Router для керування навігацією та відображення локалізованих компонентів.
 */
export const LocaleRouter: FC<PropsWithChildren> = ({ children }) => (
  <BrowserRouter>
    <Routes>
      {locales
        .filter(
          (locale) => middleware.prefixDefault || locale !== defaultLocale
        )
        .map((locale) => (
          <Route
            // Шаблон маршруту для захоплення локалі (наприклад, /en/, /fr/) і відповідності всім наступним шляхам
            path={`/${locale}/*`}
            key={locale}
            element={<AppLocalized locale={locale}>{children}</AppLocalized>} // Обгортає дочірні елементи з управлінням локаллю
          />
        ))}

      {
        // Якщо префіксування локалі за замовчуванням відключено, відобразити дочірні елементи безпосередньо за кореневим шляхом
        !middleware.prefixDefault && (
          <Route
            path="*"
            element={
              <AppLocalized locale={defaultLocale}>{children}</AppLocalized>
            } // Обгортає дочірні елементи з управлінням локаллю
          />
        )
      }
    </Routes>
  </BrowserRouter>
);

      Потім ви можете використовувати компонент LocaleRouter у вашому застосунку:

      src/App.tsx
      import { LocaleRouter } from "./components/LocaleRouter";
import type { FC } from "react";

// ... Ваш компонент AppContent

const App: FC = () => (
  <LocaleRouter>
    <AppContent />
  </LocaleRouter>
);

    8. Змінити URL при зміні локалі

      Необов'язково

      Щоб змінювати URL при зміні локалі, ви можете використовувати проп onLocaleChange, що надається хуком useLocale. Паралельно можна використовувати хуки useLocation та useNavigate з react-router-dom для оновлення шляху URL.

      src/components/LocaleSwitcher.tsx
      import { useLocation, useNavigate } from "react-router-dom";
import {
  Locales,
  getHTMLTextDir,
  getLocaleName,
  getLocalizedUrl,
} from "intlayer";
import { useLocale } from "react-intlayer";
import { type FC } from "react";

const LocaleSwitcher: FC = () => {
  const { pathname, search } = useLocation(); // Отримати поточний шлях URL. Приклад: /fr/about?foo=bar
  const navigate = useNavigate();

  const { locale, availableLocales, setLocale } = useLocale({
    onLocaleChange: (locale) => {
      // Сформувати URL з оновленою локаллю
      // Приклад: /es/about?foo=bar
      const pathWithLocale = getLocalizedUrl(`${pathname}${search}`, locale);

      // Оновити шлях URL
      navigate(pathWithLocale);
    },
  });

  return (
    <div>
      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
      <div id="localePopover" popover="auto">
        {availableLocales.map((localeItem) => (
          <a
            href={getLocalizedUrl(location.pathname, localeItem)}
            hrefLang={localeItem}
            aria-current={locale === localeItem ? "page" : undefined}
            onClick={(e) => {
              e.preventDefault();
              setLocale(localeItem);
            }}
            key={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={Locales.ENGLISH}>
              {/* Назва мови англійською, напр. French */}
              {getLocaleName(localeItem, Locales.ENGLISH)}
            </span>
          </a>
        ))}
      </div>
    </div>
  );
};

      Посилання на документацію:

    9. Змінити атрибути мови та напрямку HTML

      Необов'язково

      Коли ваш застосунок підтримує кілька мов, важливо оновлювати атрибути lang та dir тега <html>, щоб вони відповідали поточній локалі. Це забезпечує:

      • Доступність: Екранні читачі та допоміжні технології покладаються на правильний атрибут lang для точного вимови та інтерпретації контенту.
      • Відображення тексту: Атрибут dir (напрямок) забезпечує правильний порядок відображення тексту (наприклад, зліва направо для англійської, справа наліво для арабської або івриту), що важливо для читабельності.
      • SEO: Пошукові системи використовують атрибут lang для визначення мови вашої сторінки, допомагаючи показувати правильний локалізований контент у результатах пошуку.

      Оновлюючи ці атрибути динамічно при зміні локалі, ви гарантуєте послідовний та доступний досвід для користувачів усіх підтримуваних мов.

      Реалізація хука

      Створіть власний хук для керування атрибутами HTML. Хук слухає зміни локалі та відповідно оновлює атрибути:

      src/hooks/useI18nHTMLAttributes.tsx
      import { useEffect } from "react";
import { useLocale } from "react-intlayer";
import { getHTMLTextDir } from "intlayer";

/**
 * Оновлює атрибути `lang` та `dir` елемента HTML <html> на основі поточної локалі.
 * - `lang`: Повідомляє браузери та пошукові системи про мову сторінки.
 * - `dir`: Забезпечує правильний порядок читання (наприклад, 'ltr' для англійської, 'rtl' для арабської).
 *
 * Це динамічне оновлення важливе для правильного відображення тексту, доступності та SEO.
 */
export const useI18nHTMLAttributes = () => {
  const { locale } = useLocale();

  useEffect(() => {
    // Оновити атрибут мови на поточну локаль.
    document.documentElement.lang = locale;

    // Встановити напрямок тексту на основі поточної локалі.
    document.documentElement.dir = getHTMLTextDir(locale);
  }, [locale]);
};

      Використання хука у вашому застосунку

      Інтегруйте хук у ваш основний компонент, щоб атрибути HTML оновлювалися щоразу, коли змінюється локаль:

      src/App.tsx
      import type { FC } from "react";
import { IntlayerProvider, useIntlayer } from "react-intlayer";
import { useI18nHTMLAttributes } from "./hooks/useI18nHTMLAttributes";
import "./App.css";

const AppContent: FC = () => {
  // Застосувати хук для оновлення атрибутів `lang` та `dir` тега <html> на основі локалі.
  useI18nHTMLAttributes();

  // ... Решта вашого компонента
};

const App: FC = () => (
  <IntlayerProvider>
    <AppContent />
  </IntlayerProvider>
);

export default App;

      Застосувавши ці зміни, ваш застосунок буде:

      • Забезпечувати правильне відображення атрибута мови (lang) відповідно до поточної локалі, що важливо для SEO та поведінки браузера.
      • Налаштовувати напрямок тексту (dir) відповідно до локалі, покращуючи читабельність та зручність використання для мов з різним порядком читання.
      • Забезпечувати більш доступний досвід, оскільки допоміжні технології покладаються на ці атрибути для оптимальної роботи.

    Налаштування TypeScript

    Intlayer використовує module augmentation для отримання переваг TypeScript та зміцнення вашої кодової бази.

    Автодоповнення

    Помилка перекладу

    Переконайтеся, що ваша конфігурація TypeScript включає автогенеровані типи.

    tsconfig.json
    {  // ... Ваші існуючі конфігурації TypeScript  "include": [    // ... Ваші існуючі конфігурації TypeScript    ".intlayer/**/*.ts", // Включити автогенеровані типи  ],}

    Конфігурація Git

    Рекомендується ігнорувати файли, згенеровані Intlayer. Це дозволяє уникнути їх коміту до вашого репозиторію Git.

    Для цього додайте наступні інструкції до вашого файлу .gitignore:

    .gitignore
    # Ігнорувати файли, згенеровані Intlayer.intlayer

    Розширення VS Code

    Щоб покращити ваш досвід розробки з Intlayer, ви можете встановити офіційне Розширення Intlayer VS Code.

    Встановити з VS Code Marketplace

    Це розширення надає:

    • Автодоповнення для ключів перекладу.
    • Виявлення помилок у реальному часі для відсутніх перекладів.
    • Вбудовані попередні перегляди перекладеного контенту.
    • Швидкі дії для легкого створення та оновлення перекладів.

    Для отримання додаткової інформації про використання розширення зверніться до документації розширення Intlayer VS Code.

    Піти далі

    Щоб піти далі, ви можете реалізувати візуальний редактор або винести ваш контент за допомогою CMS.

    Analog
    React Native та Expo