@intlayer/docs 9.5.2 → 9.5.4-canary.0

package/blog/pl/how_to_pick_react_i18n_library.md

@@ -0,0 +1,549 @@
+---
+createdAt: 2026-09-16
+updatedAt: 2026-09-16
+title: "Jak wybrać odpowiednią bibliotekę i18n dla React w 2026 roku"
+description: Przewodnik decyzyjny dotyczący internacjonalizacji React. Na jakie pytania odpowiedzieć przed porównaniem react-i18next, react-intl, Lingui, use-intl, Paraglide i Intlayer oraz ile każdy wybór kosztuje pod względem rozmiaru bundle, typowania i utrzymania.
+keywords:
+  - react i18n
+  - react internationalization
+  - react internacjonalizacja
+  - react-i18next
+  - react-intl
+  - Lingui
+  - use-intl
+  - Paraglide
+  - Intlayer
+  - porównanie bibliotek i18n
+slugs:
+  - blog
+  - how-to-pick-react-i18n-library
+author: aymericzip
+---
+
+# 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](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/next-i18next_vs_next-intl_vs_intlayer.md).
+
+![Ekosystem bibliotek React i18n](https://github.com/aymericzip/intlayer/blob/main/docs/assets/cloud_i18n_logo.webp?raw=true)
+
+## Spis treści
+
+<TOC/>
+
+## 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.
+
+![Historia bibliotek JavaScript i18n](https://github.com/aymericzip/intlayer/blob/main/docs/assets/history_i18n.webp?raw=true)
+
+<AccordionGroup>
+<Accordion header="Słowniki w czasie wykonywania (2011 do 2017): i18next, react-intl">
+
+Katalogi JSON ładowane do pamięci, `t("a.b")` wyszukiwane w runtime, ICU lub niestandardowa składnia parsowana w przeglądarce. Największe ekosystemy, najcięższe runtime, typowanie jest opcjonalne.
+
+</Accordion>
+<Accordion header="Makra czasu kompilacji (2018 do 2021): Lingui, typesafe-i18n">
+
+Wiadomości wyodrębniane podczas budowania, kompilowane do kompaktowych katalogów, typowane argumenty. Dodatkowy krok budowania (`extract`, `compile`) w zamian za mniejsze paczki bundle.
+
+</Accordion>
+<Accordion header="Podejście zorientowane na serwer (2022 do 2024): use-intl / next-intl">
+
+Zaprojektowane z myślą o SSR i Server Components. Renderowanie na serwerze, hydratacja tylko tego, czego klient potrzebuje. Wciąż oparte na kluczach i scentralizowane.
+
+</Accordion>
+<Accordion header="Kompilator i współdzielona treść (2024 do 2026): Paraglide, Intlayer, wuchale">
+
+Treść jest kompilowana do funkcji zdatnych do tree-shakingu lub słowników per-komponent. Typy są generowane automatycznie, brakujące tłumaczenia powodują błąd kompilacji, a tłumaczenie AI działa bezpośrednio z poziomu CLI.
+
+</Accordion>
+</AccordionGroup>
+
+Artykuł [historia JavaScript i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/history_of_i18n.md) 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ę.
+
+![Teoretyczny wyciek treści według architektury](https://github.com/aymericzip/intlayer/blob/main/docs/assets/theorical_content_leakage.webp?raw=true)
+
+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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/benchmark/index.md) 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](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/per-component_vs_centralized_i18n.md) zagłębia się w kwestię utrzymania tego samego wyboru.
+
+## Kandydaci
+
+Rozmiary bibliotek pochodzą z [benchmarku TanStack Start](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/benchmark/tanstack.md): provider oraz hook w pustym komponencie, po bundlowaniu, tree-shakingu i minifikacji, 10 stron i 10 języków. Treść jest mierzona osobno.
+
+| Biblioteka              | Fala         | Model treści                                   | Bezpieczeństwo typów                   | Format wiadomości                      | Rozmiar biblioteki                                   |
+| :---------------------- | :----------- | :--------------------------------------------- | :------------------------------------- | :------------------------------------- | :--------------------------------------------------- |
+| `react-i18next`         | Runtime      | Centralny JSON, przestrzenie nazw              | 2/5 — Opcjonalne (`CustomTypeOptions`) | i18next (przyrostki dla liczb mnogich) | ~18.4 kB                                             |
+| `react-intl` (FormatJS) | Runtime      | Centralny JSON, ICU                            | 2/5 — Opcjonalne (ekstrakcja + unia)   | ICU                                    | ~15.3 kB                                             |
+| `use-intl`              | Server-first | Centralny JSON, ICU                            | 2/5 — Opcjonalne (declaration merging) | ICU                                    | ~14.1 kB                                             |
+| `@tolgee/react`         | Runtime      | Centralny, edycja w kontekście                 | 1/5 — Brak                             | ICU                                    | ~11.1 kB                                             |
+| Lingui                  | Macro        | Tekst źródłowy w kodzie, skompilowane katalogi | 2/5 — Dobre, z kompilatora             | ICU przez makra                        | ~11.8 kB                                             |
+| Paraglide               | Compiler     | Projekt inlang, wygenerowane funkcje           | 3.5/5 — Generowane                     | Własny                                 | Bliski zeru (dzięki kodowi generowanemu w projekcie) |
+| Intlayer                | Compiler     | `.content.ts` per komponent                    | 5/5 — Generowane, domyślnie włączone   | Intlayer (+ ICU, i18next, PO)          | ~5.0 kB                                              |
+
+> 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.
+> Bezpieczeństwo typów: 5/5 oznacza, że klucze, parametry i każda lokalizacja są sprawdzane bez ręcznej konfiguracji, w tym formatery URL i helpery.
+
+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
+
+<AccordionGroup>
+<Accordion header="Prototyp, mały zespół, niewiele języków">
+
+Wybierz najprostszą działającą opcję i nie komplikuj konfiguracji. `react-i18next` z pojedynczym plikiem JSON per język sprawdzi się doskonale, a dekada odpowiedzi na Stack Overflow zaoszczędzi Twój czas. Pomiń przestrzenie nazw, dopóki nie będą potrzebne. Jeśli prototyp przekształci się w produkt, zaplanuj migrację do treści modułowej; adapter kompatybilności [react-i18next compat adapter](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/compat/react-i18next.md) pozwala przeprowadzić ją stopniowo.
+
+</Accordion>
+<Accordion header="Tłumaczenia pochodzą z agencji lub TMS obsługującego ICU">
+
+Twój format katalogu został już narzucony z góry. `react-intl` natywnie obsługuje ICU, a narzędzia ekstrakcji FormatJS są zbudowane pod taki proces. `use-intl` również odczytuje ICU. `react-i18next` w przeciwnym razie wymaga wtyczki ICU i własnych kluczy liczb mnogich. Obsługa ICU w Intlayer jest wciąż częściowa, więc jeśli już dziś otrzymujesz ciągi ICU, potraktuj to jako kwestię blokującą do czasu pełnej implementacji.
+
+</Accordion>
+<Accordion header="Duża aplikacja, wiele tras, budżet bundle ma znaczenie">
+
+Wybierz modułową treść i dynamiczne ładowanie jako standard domyślny, a nie tylko konwencję. `Lingui` oraz `Paraglide` osiągają to poprzez kompilację. Intlayer osiąga to dzięki deklaracjom per-komponent, a kompilator dostarcza tylko to, co renderuje dana trasa. W przypadku `react-i18next` lub `use-intl` zaplanuj strategię przestrzeni nazw i leniwego ładowania już pierwszego dnia i egzekwuj ją podczas code review, ponieważ narzędzia tego nie wymuszą.
+
+</Accordion>
+<Accordion header="Bezpieczeństwo typów jest bezdyskusyjne">
+
+Każdą bibliotekę opartą na kluczach można otypować, ale prawie żadna nie oferuje tego od razu po instalacji. Jeśli nie chcesz utrzymywać mechanizmu declaration merging, który musi obsługiwać leniwie ładowane przestrzenie nazw, wybierz bibliotekę, w której typy są generowane z treści: `Lingui`, `Paraglide` lub Intlayer. Artykuł [wykrywanie brakujących tłumaczeń](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/detecting_missing_translations.md) porównuje, co każde rozwiązanie wyłapuje w czasie budowania.
+
+</Accordion>
+<Accordion header="Dużo bogatej treści: markdown, linki wewnątrz zdań, komponenty per-locale">
+
+Rozbudowane węzły to miejsce, w którym podejście `t()` zwracające string przestaje się sprawdzać. `react-i18next` i `Lingui` mają `<Trans>`, `react-intl` posiada tagi rich text, a wszystkie te rozwiązania są bardziej kłopotliwe niż prosty przypadek tekstowy. Węzły treści Intlayer przyjmują bezpośrednio JSX, markdown oraz zagnieżdżone obiekty, co sprawdza się znacznie lepiej, gdy treść to coś więcej niż tylko etykiety interfejsu.
+
+</Accordion>
+<Accordion header="Tłumaczenia będą generowane przez AI i weryfikowane przez programistów">
+
+Wtedy scentralizowany JSON przestaje być wymogiem, ponieważ nie ma potrzeby importu do zewnętrznego TMS. Treść umieszczona przy komponentach wraz z CLI uzupełniającym brakujące języki to krótsza droga. Polecenie `fill` w Intlayer działa z Twoim własnym kluczem API (OpenAI, Anthropic, Mistral, Gemini) i tłumaczy wyłącznie to, co uległo zmianie. Paraglide i Tolgee oferują hostowane odpowiedniki z własnymi planami taryfowymi.
+
+</Accordion>
+<Accordion header="Możliwe przejście na Next.js App Router w przyszłości">
+
+Kontekst React nie przekracza granicy między serwerem a klientem. Biblioteki zbudowane wyłącznie na hooku klienckim (`react-i18next`, `react-intl`) będą wymagały równoległego API serwerowego w dniu wdrożenia RSC. `use-intl` (jako `next-intl`) oraz Intlayer (jako `next-intlayer`) mają już ten podział wbudowany. Przeczytaj [artykuł o Next.js i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/list_i18n_technologies/frameworks/nextjs.md) przed standaryzacją wzorca.
+
+</Accordion>
+</AccordionGroup>
+
+## 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.
+
+<Tabs defaultTab="react-i18next">
+  <Tab label="react-i18next" value="react-i18next">
+
+  <Tabs group="locale">
+  <Tab value="en" label="Angielski">
+
+```json fileName="public/locales/en/cart.json"
+{
+  "title": "Your cart",
+  "items_one": "{{count}} item",
+  "items_other": "{{count}} items"
+}
+```
+
+  </Tab>
+  <Tab value="fr" label="Francuski">
+
+```json fileName="public/locales/fr/cart.json"
+{
+  "title": "Votre panier",
+  "items_one": "{{count}} article",
+  "items_other": "{{count}} articles"
+}
+```
+
+  </Tab>
+  <Tab value="es" label="Hiszpański">
+
+```json fileName="public/locales/es/cart.json"
+{
+  "title": "Tu carrito",
+  "items_one": "{{count}} artículo",
+  "items_other": "{{count}} artículos"
+}
+```
+
+  </Tab>
+  </Tabs>
+
+```tsx fileName="src/components/CartSummary.tsx"
+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>
+  );
+};
+```
+
+Liczby mnogie to klucze z przyrostkami rozwiązywane przez `Intl.PluralRules`. `t` ma typ `(key: string) => string`, chyba że zadeklarujesz `CustomTypeOptions`, więc `t("titel")` skompiluje się bez błędu.
+
+  </Tab>
+  <Tab label="react-intl" value="react-intl">
+
+  <Tabs group="locale">
+  <Tab value="en" label="Angielski">
+
+```json fileName="src/locales/en.json"
+{
+  "cart.title": "Your cart",
+  "cart.items": "{count, plural, one {# item} other {# items}}"
+}
+```
+
+  </Tab>
+  <Tab value="fr" label="Francuski">
+
+```json fileName="src/locales/fr.json"
+{
+  "cart.title": "Votre panier",
+  "cart.items": "{count, plural, one {# article} other {# articles}}"
+}
+```
+
+  </Tab>
+  <Tab value="es" label="Hiszpański">
+
+```json fileName="src/locales/es.json"
+{
+  "cart.title": "Tu carrito",
+  "cart.items": "{count, plural, one {# artículo} other {# artículos}}"
+}
+```
+
+  </Tab>
+  </Tabs>
+
+```tsx fileName="src/components/CartSummary.tsx"
+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>
+  );
+};
+```
+
+ICU od początku do końca, czyli format najczęściej eksportowany przez platformy TMS. Typy dla `id` wynikają z kroku ekstrakcji `formatjs` oraz wygenerowanej unii, nie są dostępne od razu po instalacji.
+
+  </Tab>
+  <Tab label="use-intl" value="use-intl">
+
+  <Tabs group="locale">
+  <Tab value="en" label="Angielski">
+
+```json fileName="messages/en.json"
+{
+  "Cart": {
+    "title": "Your cart",
+    "items": "{count, plural, one {# item} other {# items}}"
+  }
+}
+```
+
+  </Tab>
+  <Tab value="fr" label="Francuski">
+
+```json fileName="messages/fr.json"
+{
+  "Cart": {
+    "title": "Votre panier",
+    "items": "{count, plural, one {# article} other {# articles}}"
+  }
+}
+```
+
+  </Tab>
+  <Tab value="es" label="Hiszpański">
+
+```json fileName="messages/es.json"
+{
+  "Cart": {
+    "title": "Tu carrito",
+    "items": "{count, plural, one {# artículo} other {# artículos}}"
+  }
+}
+```
+
+  </Tab>
+  </Tabs>
+
+```tsx fileName="src/components/CartSummary.tsx"
+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>
+  );
+};
+```
+
+Taka sama struktura jak w `next-intl` bez powiązań z Next.js. Klucze są typowane po rozszerzeniu `AppConfig` o typ wiadomości; podział na przestrzenie nazw leży po Twojej stronie.
+
+  </Tab>
+  <Tab label="Lingui" value="lingui">
+
+```po fileName="src/locales/fr/messages.po"
+msgid "Your cart"
+msgstr "Votre panier"
+
+msgid "{count, plural, one {# item} other {# items}}"
+msgstr "{count, plural, one {# article} other {# articles}}"
+```
+
+```tsx fileName="src/components/CartSummary.tsx"
+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>
+);
+```
+
+Język źródłowy znajduje się w komponencie; inne języki trafiają do plików `.po` pod skróconymi identyfikatorami po wykonaniu `lingui extract`. Pominięcie `extract` lub `compile` powoduje cichy powrót do języka angielskiego.
+
+  </Tab>
+  <Tab label="Paraglide" value="paraglide">
+
+  <Tabs group="locale">
+  <Tab value="en" label="Angielski">
+
+```json fileName="messages/en.json"
+{
+  "cart_title": "Your cart",
+  "cart_items": "{count} items"
+}
+```
+
+  </Tab>
+  <Tab value="fr" label="Francuski">
+
+```json fileName="messages/fr.json"
+{
+  "cart_title": "Votre panier",
+  "cart_items": "{count} articles"
+}
+```
+
+  </Tab>
+  <Tab value="es" label="Hiszpański">
+
+```json fileName="messages/es.json"
+{
+  "cart_title": "Tu carrito",
+  "cart_items": "{count} artículos"
+}
+```
+
+  </Tab>
+  </Tabs>
+
+```tsx fileName="src/components/CartSummary.tsx"
+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>
+);
+```
+
+Każda wiadomość to wygenerowana, typowana funkcja, więc brakujący klucz jest błędem importu. Folder `paraglide/` jest generowany w Twoim repozytorium i odświeżany przy każdej zmianie.
+
+  </Tab>
+  <Tab label="Intlayer" value="intlayer">
+
+```ts fileName="src/components/cartSummary.content.ts"
+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;
+```
+
+```tsx fileName="src/components/CartSummary.tsx"
+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>
+  );
+};
+```
+
+Wszystkie języki w jednym pliku obok komponentu. Typy są generowane podczas budowania, więc `title` podpowiada się w autouzupełnianiu, a literówka wywoła błąd `tsc` bez konieczności konfiguracji declaration merging. Usunięcie folderu usuwa powiązane stringi.
+
+  </Tab>
+</Tabs>
+
+Korzystasz już z `react-i18next`, `react-intl` lub `Lingui`? Adaptery kompatybilności ([react-i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/compat/react-i18next.md), [react-intl](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/compat/react-intl.md), [Lingui](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/compat/lingui.md)) 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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/migration_from_react-i18next_to_intlayer.md).
+
+## 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.
+
+![Ranking bibliotek JavaScript i18n](https://github.com/aymericzip/intlayer/blob/main/docs/assets/alphabet_rank_i18n_lib.webp?raw=true)
+
+**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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/agent_skills.md) lub [serwer MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/mcp_server.md), 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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/lsp.md) lub [rozszerzenie VS Code](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/vs_code_extension.md) pokazujące tłumaczenie po najechaniu kursorem i przenoszące do deklaracji, [CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/cli/index.md) do uzupełniania (fill), testowania i synchronizacji (push), [kompilator](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/compiler.md) lub ekstraktor, który wyciąga zakodowane na stałe ciągi z komponentów, aby nie zarządzać każdym ciągiem klucz po kluczu, a także możliwość edycji treści przez osoby nietechniczne ([edytor wizualny](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/intlayer_visual_editor.md) lub [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/intlayer_CMS.md)) bez konieczności tworzenia pull requesta.
+
+## Najczęściej zadawane pytania (FAQ)
+
+<FAQ>
+
+<Question title="Czy react-i18next jest nadal dobrym domyślnym wyborem w 2026 roku?">
+
+Tak, dla większości zespołów. Posiada największy ekosystem i najwięcej materiałów w sieci. Koszty są realne, ale przewidywalne: najcięższy runtime, niestandardowy format liczb mnogich oraz bezpieczeństwo typów i podział na moduły, które musisz samodzielnie skonfigurować i utrzymać.
+
+</Question>
+
+<Question title="Czy potrzebuję biblioteki opartej na kompilatorze?">
+
+Tylko wtedy, gdy rozmiar bundle, wygenerowane typy lub sprawdzanie brakujących kluczy w czasie budowania należą do Twoich kluczowych wymagań. W przypadku małej aplikacji z dwoma językami biblioteka działająca w czasie wykonywania jest prostsza. Artykuł [kompilator kontra deklaratywne i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/compiler_vs_declarative_i18n.md) wyjaśnia, jakie korzyści dają kompilatory i jakie mogą stwarzać wyzwania.
+
+</Question>
+
+<Question title="Czy mogę zmienić bibliotekę później bez przepisywania każdego komponentu?">
+
+Częściowo. Biblioteki oparte na kluczach dzielą na tyle podobną strukturę, że adapter kompatybilności może zmapować jedno API na drugie, co właśnie robią adaptery Intlayer. Formaty wiadomości (ICU vs i18next vs funkcje pomocnicze) nie konwertują się automatycznie, więc liczby mnogie oraz interpolacja będą elementami wymagającymi modyfikacji.
+
+</Question>
+
+<Question title="Czy wybór biblioteki wpływa na SEO?">
+
+Pośrednio. To, co widzą roboty wyszukiwarek, zależy od routingu, `hreflang`, atrybutu `<html lang>` oraz od tego, czy tekst znajduje się w kodzie HTML renderowanym na serwerze. Niektóre biblioteki dostarczają do tego pomocniki, większość pozostawia to programiście. Zobacz [przewodnik po hreflang](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/hreflang_guide_multilingual_seo.md).
+
+</Question>
+
+</FAQ>
+
+## Więcej informacji
+
+- [Benchmark bibliotek i18n: rozmiar bundle, wycieki treści i czasy przełączania języków](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/benchmark/index.md) oraz [raport TanStack Start](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/benchmark/tanstack.md)
+- [React i18n: jak działa model providera i jakie generuje koszty](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/list_i18n_technologies/frameworks/react.md)
+- [react-i18next vs react-intl vs Intlayer, porównanie funkcja po funkcji](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/react-i18next_vs_react-intl_vs_intlayer.md)
+- [next-i18next vs next-intl vs Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/next-i18next_vs_next-intl_vs_intlayer.md)
+- [Historia JavaScript i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/history_of_i18n.md)
+- [Kompilator kontra deklaratywne i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/compiler_vs_declarative_i18n.md)
+- [Per-component vs scentralizowane i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/per-component_vs_centralized_i18n.md)
+- [Jak działa optymalizacja bundle podczas budowania](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/bundle_optimization.md)
+- [Konfiguracja i18n w aplikacji Vite + React](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/intlayer_with_vite+react.md)
+- Ten sam przewodnik dla [Vue](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/how_to_pick_vue_i18n_library.md), [Svelte](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/how_to_pick_svelte_i18n_library.md) i [Solid](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/how_to_pick_solid_i18n_library.md)