Jak wybrać odpowiednią bibliotekę i18n dla React

React nie dostarcza żadnego wbudowanego mechanizmu i18n. Biblioteka, którą wybierzesz na samym początku, decyduje o tym, jak przechowywane są tłumaczenia, jak trafiają do bundle i jak duża część pracy spadnie na Ciebie przez kolejne lata. Większość zespołów wybiera rozwiązanie na podstawie popularności, a kompromisy odkrywa dopiero przy 2 000 kluczy.

Ten przewodnik podchodzi do tematu od drugiej strony: najpierw odpowiedz na kilka pytań dotyczących Twojego projektu, a następnie dopasuj odpowiedzi do pasujących bibliotek. Koncentruje się na czystym React (Vite, React Router, TanStack Start). Next.js ma własne ograniczenia, opisane w porównaniu Next.js.

Spis treści

Sześć pytań, na które warto odpowiedzieć przed porównaniem bibliotek

Tabela funkcji jest bezużyteczna, jeśli nie wiesz, które wiersze mają dla Ciebie znaczenie. Przejdź najpierw przez poniższe punkty.

1. Jak renderowana jest aplikacja? Tylko SPA, SSR z hydratacją czy React Server Components. Hooki oparte na kontekście działają wszędzie w SPA. W przypadku RSC hook wymusza "use client" na każdym komponencie renderującym tekst, więc będziesz potrzebować również API po stronie serwera.
2. Kto tworzy tłumaczenia? Programiści, wewnętrzny zespół korzystający z TMS, agencja dostarczająca pliki ICU czy pipeline AI. To determinuje format katalogu bardziej niż jakikolwiek szczegół API.
3. Ile masz języków (locales) i podstron? Dwie wersje językowe i pięć stron mogą pozwolić sobie na wysłanie wszystkiego do klienta. Dziesięć wersji językowych i pięćdziesiąt tras już nie, a strategia ładowania staje się głównym kosztem.
4. Czy potrzebujesz typowania kluczy? Literówka w t("checkout.totl") skompiluje się w każdej bibliotece opartej na kluczach, chyba że samodzielnie skonfigurujesz typy. Zdecyduj, czy to jest akceptowalne.
5. Co zawiera string? Zwykły tekst, liczbę mnogą czy zdania z komponentem <Link> w środku. Bogata treść (rich content) to miejsce, w którym większość API staje się niewygodna.
6. Jak długo będzie żył projekt? Trzymiesięczny prototyp i pięcioletni produkt nie potrzebują takiej samej ilości konfiguracji narzędzi budowania.

Zapisz swoje odpowiedzi. Wszystko poniżej odnosi się właśnie do nich.

Krajobraz w jednym ujęciu

Piętnaście lat JavaScript i18n mieści się w czterech falach architektonicznych, a biblioteki React, które będziesz porównywać, pochodzą z różnych etapów.

Artykuł historia JavaScript i18n szczegółowo opisuje, jak każda fala odpowiadała na problemy poprzedniej.

Najważniejsza decyzja: gdzie żyje treść i kiedy jest ładowana

Każda biblioteka React i18n ma podobny schemat: store, provider i hook. Cokolwiek otrzymuje provider, ląduje w bundle klienta lub w payloadzie hydratacji. Dwa kluczowe wybory strukturalne to:

• Treść scentralizowana czy modułowa (scoped). Jeden plik en.json dla całej aplikacji, czy jedna deklaracja na komponent (lub na przestrzeń nazw).
• Import statyczny czy dynamiczny. Wszystko spakowane przy starcie, czy aktywny język i trasa pobierane na żądanie.

Poniższy wykres szacuje rozmiar danych dla teoretycznej aplikacji mającej od 1 do 10 stron, przetłumaczonej na 1 do 10 języków, z około 30 KB tekstu na stronę.

Scentralizowana treść ze statycznymi importami rośnie wzdłuż obu osi: 10 stron razy 10 języków to 300 KB tekstu na każdej stronie. Dynamiczne importy eliminują oś języków. Modułowość (scoping) eliminuje oś stron. Tylko połączenie obu podejść pozwala zachować stały, niski rozmiar.

Nie jest to cecha samej biblioteki, lecz kwestia dyscypliny w projekcie. react-i18next może być podzielony na przestrzenie nazw z asynchronicznymi backendami. use-intl można podzielić per trasa. Jednak nic tego nie wymusza, a współdzielony <Button> sięgający po t("common:cta") po cichu czyni common zależnością każdej trasy. W benchmarku jest to mierzone jako "wyciek z innych tras" i "wyciek z innych języków" i to stąd wynika większość różnic między bibliotekami.

Jeśli Twoją odpowiedzią na pytanie 3 było "wiele języków, wiele stron", nadaj tej sekcji większą wagę niż jakimkolwiek preferencjom API. Wpis per-component vs centralized i18n zagłębia się w kwestię utrzymania tego samego wyboru.

Kandydaci

Rozmiary bibliotek pochodzą z benchmarku TanStack Start: provider oraz hook w pustym komponencie, po bundlowaniu, tree-shakingu i minifikacji, 10 stron i 10 języków. Treść jest mierzona osobno.

Liczby są zrzutem stanu w wersjach z benchmarku i zmieniają się wraz z kolejnymi wydaniami. Przed podjęciem decyzji wyłącznie na podstawie rozmiaru uruchom benchmark we własnej aplikacji.

Dwie rzeczy, których tabela nie pokazuje: Paraglide nie dodaje niemal żadnej biblioteki runtime, ponieważ generuje kod bezpośrednio w Twoim repozytorium, co oznacza krok regeneracji przed każdym commitem i potencjalne konflikty scalania w wygenerowanych plikach. Z kolei Intlayer wymaga wtyczki do bundlera (vite-intlayer lub odpowiednika), więc nie może działać w środowisku bez etapu budowania.

Dopasuj swoje odpowiedzi do biblioteki

Gdzie każda biblioteka ma swoje ograniczenia

Szczere podsumowanie słabszych stron, ponieważ każda opcja ma swoje kompromisy.

• react-i18next: najcięższa w zestawieniu, własny format liczb mnogich, typy wymagają ręcznej konfiguracji i utrzymania, nieużywane klucze gromadzą się po cichu.
• react-intl: rozwlekłe DX (useIntl(), a następnie formatMessage({ id })), globalna instancja powiązana z wieloma węzłami.
• use-intl: prosta na start, uciążliwa w optymalizacji. Przestrzenie nazw, dynamiczne ładowanie i typy użyte razem znacząco spowalniają development.
• Lingui: dodatkowy krok budowania extract / compile, kilka nakładających się składni (t(), tagged template, i18n.t(), <Trans>), które dezorientują zarówno ludzi, jak i asystentów AI.
• Paraglide: wygenerowane pliki w repozytorium, tree-shaking nie zadziałał w benchmarku React, a język jest odczytywany ze storage przy każdym węźle zamiast ze store'a.
• Tolgee: brak typowania kluczy, trudniejszy onboarding, głównym atutem jest edycja w kontekście aplikacji.
• Intlayer: wymagana wtyczka do budowania, mniejszy ekosystem, częściowe wsparcie dla ICU, treść rozproszona w całym codebase z założenia, więc wyeksportowanie jednego pliku JSON dla tłumacza wymaga dedykowanych narzędzi.
• gt-react, lingo.dev: niezalecane w benchmarku ze względu na błędy limitów przy budowaniu, uzależnienie od dostawcy (vendor lock-in) i problemy z reaktywnością wymagające wymuszania ponownego renderowania providera.

Jak każda opcja wygląda w kodzie

Ten sam komponent, podsumowanie koszyka z tytułem i liczbą mnogą, napisany przy użyciu każdego z kandydatów. Najciekawszym elementem nie jest sam komponent, lecz miejsce przechowywania treści i to, co wie o niej system sprawdzania typów.

{
  "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({
      pl: "Twój koszyk",
      en: "Your cart",
      fr: "Votre panier",
      es: "Tu carrito",
    }),
    items: t({
      pl: plural({ one: "{{count}} element", other: "{{count}} elementów" }),
      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>
  );
};

Korzystasz już z react-i18next, react-intl lub Lingui? Adaptery kompatybilności (react-i18next, react-intl, Lingui) tworzą aliasy importów na poziomie bundlera, dzięki czemu dotychczasowe API nadal działa, podczas gdy Ty migrujesz kod komponent po komponencie. Resztę opisuje przewodnik migracji.

Zanim podejmiesz ostateczną decyzję

Tabela funkcji pokazuje, co biblioteka potrafi dzisiaj. Poniższe punkty pokazują, jak będzie wyglądać codzienna praca z nią.

Sprawdź aktywność repozytorium.

Liczba commitów, czas odpowiedzi na zgłoszenia i to, czy ostatnie wydanie minor pojawiło się w tym roku. Dobry projekt bez aktywnego opiekuna to przyszła migracja.

Nie wybieraj wyłącznie na podstawie pobrań z npm.

Najczęściej instalowana biblioteka to ta, która powstała jako pierwsza, a nie ta, która najlepiej pasuje do bazy kodu React w 2026 roku. Liczba pobrań mierzy historię, a nie dopasowanie do bieżących potrzeb.

Sprawdź, kto finansuje maintainera i co sprzedaje.

i18next jest wspierany przez Locize. next-intl / use-intl, vue-i18n, svelte-i18n i Lingui są wspierane przez Crowdin. Tolgee, Paraglide (inlang) i Intlayer prowadzą własne platformy. Dostawca, którego przychód opiera się na hostowanym tłumaczeniu, ma niewielki interes w tym, aby tłumaczenie wewnątrz Twojego łańcucha narzędzi było darmowe. Intlayer jako jedyny z tego zestawu oferuje tłumaczenie AI przez CLI z Twoim własnym kluczem API oraz CMS, który możesz hostować samodzielnie.

Czy rozwiązanie jest gotowe na agentów AI?

Agenci wciąż miewają trudności z i18n: zapominają o wersjach językowych, wymyślają klucze i mieszają składnie wiadomości. Czy biblioteka dostarcza Agent Skills lub serwer MCP, aby agent mógł listować, uzupełniać i testować treść? Oraz czy ładowanie treści jest domyślnie zoptymalizowane, czy ktoś musi co kwartał weryfikować przestrzenie nazw i leniwe importy?

Bezpieczeństwo typów od razu po instalacji.

Nie "możliwe do otypowania po dodatkowej konfiguracji", ale "błędny klucz wywołuje błąd tsc w nowo zainstalowanym projekcie". Sprawdź, co dzieje się z kluczem, który nie istnieje, oraz z językiem, w którym brakuje jednego tłumaczenia.

Wykrywanie nieużywanej treści.

Katalogi z czasem tylko rosną. Proces budowania w Intlayer usuwa nieużywane pola i rejestruje je w logach (build.purge). Paraglide osiąga to dzięki architekturze, ponieważ niewywołana funkcja wiadomości jest usuwana w procesie tree-shakingu. Wszystkie pozostałe narzędzia pozostawiają czyszczenie po Twojej stronie.

Developer Experience.

Czas od konfiguracji do pierwszego przetłumaczonego ciągu znaków, LSP lub rozszerzenie VS Code pokazujące tłumaczenie po najechaniu kursorem i przenoszące do deklaracji, CLI do uzupełniania (fill), testowania i synchronizacji (push), a także możliwość edycji treści przez osoby nietechniczne (edytor wizualny lub CMS) bez konieczności tworzenia pull requesta.

Najczęściej zadawane pytania (FAQ)

Więcej informacji

• Benchmark bibliotek i18n: rozmiar bundle, wycieki treści i czasy przełączania języków oraz raport TanStack Start
• React i18n: jak działa model providera i jakie generuje koszty
• react-i18next vs react-intl vs Intlayer, porównanie funkcja po funkcji
• next-i18next vs next-intl vs Intlayer
• Historia JavaScript i18n
• Kompilator kontra deklaratywne i18n
• Per-component vs scentralizowane i18n
• Jak działa optymalizacja bundle podczas budowania
• Konfiguracja i18n w aplikacji Vite + React
• Ten sam przewodnik dla Vue, Svelte i Solid