Как выбрать подходящую библиотеку i18n для React

React не поставляется со встроенными примитивами для i18n. Библиотека, которую вы выберете в первый же день, определяет, как будут храниться переводы, как они попадут в bundle и какой объем работы останется за вами на ближайшие несколько лет. Большинство команд выбирают по популярности, а затем сталкиваются с компромиссами, когда проект разрастается до 2 000 ключей.

Это руководство предлагает пойти от обратного: сначала ответьте на несколько вопросов о вашем проекте, а затем сопоставьте ответы с подходящими библиотеками. Оно ориентировано на чистый React (Vite, React Router, TanStack Start). У Next.js есть свои ограничения, рассмотренные в сравнении Next.js.

Table of Contents

Шесть вопросов перед сравнением библиотек

Таблица возможностей бесполезна, если вы не знаете, какие строки важны именно для вас. Сначала пройдитесь по этим пунктам.

1. Как рендерится приложение? Только SPA, SSR с гидратацией или React Server Components. Хуки на основе context работают везде в SPA. При использовании RSC хук вынуждает указывать "use client" для каждого компонента, отображающего текст, поэтому вам также потребуется server-side API.
2. Кто пишет переводы? Разработчики, внутренняя команда через TMS, агентство, предоставляющее файлы ICU, или AI-пайплайн. Это определяет формат каталога в гораздо большей степени, чем любые детали API.
3. Сколько локалей и страниц? Две локали и пять страниц могут позволить себе отправлять всё сразу. Десять локалей и пятьдесят маршрутов не могут, и стратегия загрузки становится главной статьей расходов.
4. Нужна ли типизация ключей? Опечатка в t("checkout.totl") скомпилируется в любой библиотеке на основе ключей, если вы не настроите типы вручную. Решите, допустимо ли это.
5. Что содержит строка? Простой текст, плюрализацию или предложения с компонентом <Link> посередине. Rich-контент, то место, где большинство API становятся неудобными.
6. Как долго проживет проект? Трехмесячный прототип и пятилетний продукт требуют совершенно разного объема build-инструментария.

Запишите ответы. Всё изложенное ниже будет опираться на них.

Общая картина

Пятнадцать лет JavaScript i18n укладываются в четыре архитектурные волны, и сравниваемые библиотеки React относятся к разным из них.

В статье об истории JavaScript i18n подробно описано, как каждая волна решала проблемы предыдущей.

Главное решение: где живет контент и когда он загружается

Каждая библиотека i18n для React устроена одинаково: store, provider, hook. Всё, что получает provider, оказывается в клиентском bundle или в данных гидратации. Поэтому существует два ключевых структурных выбора:

• Централизованный или локальный (scoped) контент. Один en.json на всё приложение или отдельное объявление для каждого компонента (или namespace).
• Статический или динамический импорт. Все данные собираются в bundle при запуске, либо активная локаль и маршрут загружаются по требованию.

На графике ниже показана расчетная нагрузка для теоретического приложения от 1 до 10 страниц, переведенного на 1–10 локалей, при объеме текста около 30 КБ на страницу.

Централизованный контент со статическими импортами растет по обеим осям: 10 страниц, умноженные на 10 локалей, дают 300 КБ текста на каждой странице. Динамические импорты убирают зависимость от локалей. Локальное разделение (scoping) убирает зависимость от страниц. Только их сочетание позволяет графику оставаться плоским.

Это свойство не самой библиотеки, а дисциплины разработки. react-i18next можно разделить с помощью namespaces и lazy backend. use-intl можно разбивать по маршрутам. Но ничто не заставляет это делать строго, и общий <Button>, вызывающий t("common:cta"), незаметно превращает common в зависимость для каждого маршрута. В бенчмарке это измеряется как "утечка из других маршрутов" и "утечка из других локалей", и именно здесь кроется большая часть разницы между библиотеками.

Если вашим ответом на вопрос №3 было "много локалей, много страниц", уделите этому разделу больше внимания, чем любым предпочтениям по API. В статье о покомпонентном и централизованном i18n этот выбор рассматривается глубже с точки зрения поддержки кода.

Кандидаты

Размеры библиотек взяты из бенчмарка TanStack Start: provider плюс hook в пустом компоненте после сборки, tree-shaking и минификации для 10 страниц и 10 локалей. Контент измеряется отдельно.

Значения представляют собой срез версий на момент проведения бенчмарка и меняются с новыми релизами. Запустите бенчмарк на своем приложении, прежде чем принимать решение только по размеру.

Две вещи, которые не отражены в таблице. Paraglide практически не добавляет размер библиотеки, поскольку генерирует код прямо в ваш репозиторий, что требует шага регенерации перед каждым коммитом и ведет к merge-конфликтам в сгенерированных файлах. А Intlayer требует плагин для bundler (vite-intlayer или аналог), поэтому его нельзя запустить в среде без сборки.

Сопоставьте ваши ответы с библиотекой

В чем слабые стороны каждой библиотеки

Честные ограничения, ведь они есть у любого решения.

• react-i18next: самая тяжелая из всех, собственный формат плюрализации, типы нужно настраивать и поддерживать вручную, неиспользуемые ключи незаметно накапливаются.
• react-intl: громоздкий DX (useIntl(), затем formatMessage({ id })), глобальный экземпляр привязан ко множеству узлов.
• use-intl: проста в начале, сложна в оптимизации. Совмещение namespaces, динамической загрузки и типов существенно замедляет разработку.
• Lingui: дополнительный шаг сборки extract / compile, несколько пересекающихся синтаксисов (t(), tagged template, i18n.t(), <Trans>), которые путают как людей, так и AI-ассистентов.
• Paraglide: сгенерированные файлы хранятся в репозитории, tree-shaking не сработал в бенчмарке React, а локаль считывается из storage на каждом узле вместо единого store.
• Tolgee: нет типизации ключей, более сложный онбординг, главным преимуществом является редактирование in-context.
• Intlayer: обязательный плагин для сборщика, меньшая экосистема, частичная поддержка ICU, контент распределен по codebase по концепции дизайна, поэтому для экспорта единого JSON для переводчика требуются специальные инструменты.
• gt-react, lingo.dev: не рекомендованы по результатам бенчмарка: ошибки квот при сборке, привязка к вендору и проблемы с реактивностью, требовавшие принудительного повторного рендеринга provider.

Как каждый вариант выглядит в коде

Один и тот же компонент, сводка корзины с заголовком и плюрализацией, реализованный на каждом из кандидатов. Самое интересное здесь не сам компонент, а то, где находится контент и что о нем знает средство проверки типов.

{
  "title": "Your cart",
  "items_one": "{{count}} item",
  "items_other": "{{count}} items"
}

import type { FC } from "react";
import { useTranslation } from "react-i18next";

export const CartSummary: FC<{ count: number }> = ({ count }) => {
  const { t } = useTranslation("cart");

  return (
    <section>
      <h2>{t("title")}</h2>
      <p>{t("items", { count })}</p>
    </section>
  );
};

{
  "cart.title": "Your cart",
  "cart.items": "{count, plural, one {# item} other {# items}}"
}

import type { FC } from "react";
import { FormattedMessage, useIntl } from "react-intl";

export const CartSummary: FC<{ count: number }> = ({ count }) => {
  const intl = useIntl();

  return (
    <section>
      <h2>
        <FormattedMessage id="cart.title" />
      </h2>
      <p>{intl.formatMessage({ id: "cart.items" }, { count })}</p>
    </section>
  );
};

{
  "Cart": {
    "title": "Your cart",
    "items": "{count, plural, one {# item} other {# items}}"
  }
}

import type { FC } from "react";
import { useTranslations } from "use-intl";

export const CartSummary: FC<{ count: number }> = ({ count }) => {
  const t = useTranslations("Cart");

  return (
    <section>
      <h2>{t("title")}</h2>
      <p>{t("items", { count })}</p>
    </section>
  );
};

msgid "Your cart"
msgstr "Votre panier"

msgid "{count, plural, one {# item} other {# items}}"
msgstr "{count, plural, one {# article} other {# articles}}"

import type { FC } from "react";
import { Plural, Trans } from "@lingui/react/macro";

export const CartSummary: FC<{ count: number }> = ({ count }) => (
  <section>
    <h2>
      <Trans>Your cart</Trans>
    </h2>
    <p>
      <Plural value={count} one="# item" other="# items" />
    </p>
  </section>
);

{
  "cart_title": "Your cart",
  "cart_items": "{count} items"
}

import type { FC } from "react";
import { m } from "../paraglide/messages.js";

export const CartSummary: FC<{ count: number }> = ({ count }) => (
  <section>
    <h2>{m.cart_title()}</h2>
    <p>{m.cart_items({ count })}</p>
  </section>
);

import { plural, t, type Dictionary } from "intlayer";

const cartSummaryContent = {
  key: "cart-summary",
  content: {
    title: t({
      ru: "Ваша корзина",
      en: "Your cart",
      fr: "Votre panier",
      es: "Tu carrito",
    }),
    items: t({
      ru: plural({
        one: "{{count}} товар",
        few: "{{count}} товара",
        many: "{{count}} товаров",
        other: "{{count}} товаров",
      }),
      en: plural({ one: "{{count}} item", other: "{{count}} items" }),
      fr: plural({ one: "{{count}} article", other: "{{count}} articles" }),
      es: plural({ one: "{{count}} artículo", other: "{{count}} artículos" }),
    }),
  },
} satisfies Dictionary;

export default cartSummaryContent;

import type { FC } from "react";
import { useIntlayer } from "react-intlayer";

export const CartSummary: FC<{ count: number }> = ({ count }) => {
  const { title, items } = useIntlayer("cart-summary");

  return (
    <section>
      <h2>{title}</h2>
      <p>{items(count)}</p>
    </section>
  );
};

Уже используете react-i18next, react-intl или Lingui? Адаптеры совместимости (react-i18next, react-intl, Lingui) создают псевдонимы для импортов на уровне bundler, благодаря чему существующий API продолжает работать, пока вы переносите проект компонент за компонентом. Остальные подробности описаны в руководстве по миграции.

Перед тем как сделать выбор

Таблица возможностей показывает, что библиотека умеет сейчас. Следующие пункты помогут понять, каково будет поддерживать ее в долгосрочной перспективе.

Проверьте активность репозитория.

Коммиты, скорость ответов в issues и выходил ли последний минорный релиз в этом году. Продуманная архитектура без поддержки, это будущая вынужденная миграция.

Не выбирайте исключительно по количеству скачиваний в npm.

Самая скачиваемая библиотека, та, что появилась первой, а не та, которая лучше всего подходит для кодовой базы React в 2026 году. Количество загрузок отражает историю, а не применимость к вашим задачам.

Узнайте, кто финансирует поддержку и какие услуги продает.

i18next поддерживается Locize. next-intl / use-intl, vue-i18n, svelte-i18n и Lingui поддерживаются Crowdin. Tolgee, Paraglide (inlang) и Intlayer развивают собственные платформы. Поставщик, чей доход строится на платном хостинге переводов, мало заинтересован в том, чтобы сделать переводы бесплатными внутри вашего toolchain. Intlayer, единственный вариант из списка, предлагающий AI-перевод через CLI с вашим собственным API-ключом, а также CMS, которую можно развернуть самостоятельно (self-host).

Готова ли библиотека к работе с AI-агентами?

Агенты все еще испытывают сложности с i18n: они забывают локали, придумывают несуществующие ключи и путают синтаксисы сообщений. Предоставляет ли библиотека Agent Skills или MCP-сервер, чтобы агент мог просматривать, заполнять и тестировать контент? Оптимизирована ли загрузка контента по умолчанию, или кому-то придется каждый квартал проверять namespaces и lazy imports?

Типобезопасность из коробки.

Не «можно типизировать с помощью дополнительных настроек», а «неверный ключ приводит к ошибке tsc сразу после установки». Проверьте, что происходит при обращении к несуществующему ключу и если для какой-то локали пропущен перевод.

Обнаружение неиспользуемого контента.

Каталоги со временем только разрастаются. Сборка Intlayer удаляет неиспользуемые поля и логирует их (build.purge). Paraglide решает эту задачу на уровне архитектуры, так как невызываемая функция сообщения исключается через tree-shaking. В остальных решениях поиск и очистка ложатся на вас.

Developer experience.

Время от начала настройки до первой переведенной строки, наличие LSP или расширения для VS Code, показывающего перевод при наведении и позволяющего перейти к объявлению, CLI для заполнения, тестирования и отправки данных, а также возможность для не-разработчиков редактировать контент (визуальный редактор или CMS) без создания pull request.

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

Дополнительные материалы

• Бенчмарк библиотек i18n: размер bundle, утечки и время переключения локалей и отчет по TanStack Start
• React i18n: как работает модель provider и сколько она стоит
• Сравнение react-i18next, react-intl и Intlayer по функциям
• next-i18next против next-intl и Intlayer
• История i18n в JavaScript
• Компиляторный против декларативного i18n
• Покомпонентный против централизованного i18n
• Как оптимизация bundle работает на этапе сборки
• Настройка i18n в приложении Vite + React
• Аналогичные руководства для Vue, Svelte и Solid