@intlayer/docs 9.4.1 → 9.4.3

package/blog/pl/i18n_testing_strategies.md

@@ -0,0 +1,179 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Jak testować tłumaczenia bez pisania kruchych testów"
+description: Co warto testować w aplikacji i18n, a czego nie. Testy renderowania oparte na providerach, pseudolokalizacja, pokrycie RTL i form liczby mnogiej oraz pułapka snapshotów.
+keywords:
+  - testowanie tłumaczeń
+  - testy i18n
+  - testing library i18n
+  - pseudolokalizacja
+  - test providera locale
+  - snapshot test i18n
+slugs:
+  - blog
+  - i18n-testing-strategies
+author: aymericzip
+---
+
+# Jak testować tłumaczenia bez pisania kruchych testów
+
+Większość zestawów testów i18n zawodzi na jeden z dwóch sposobów. Albo sprawdzają dosłowną treść, przez co każda zmiana sformułowania psuje pięćdziesiąt testów i zespół ostatecznie je usuwa. Albo renderują wszystko w domyślnym języku, nie weryfikując niczego dla pozostałych siedemnastu. Obie ścieżki prowadzą do tego samego: zestawu testów, któremu nikt nie ufa.
+
+## Spis treści
+
+<TOC/>
+
+## Wzorce są niezależne od biblioteki
+
+Każdy poniższy wzorzec działa na dowolnym stosie i18n. Zamień provider na `I18nextProvider`, `NextIntlClientProvider` lub `IntlProvider`, a testy pozostaną identyczne, ponieważ weryfikują wyrenderowany wynik, a nie API konkretnej biblioteki.
+
+Narzędzia pokrycia również można łatwo przenieść: dzięki [wtyczce Sync JSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/plugins/sync-json.md) wskazującej na istniejące katalogi lub [adapterowi kompatybilności](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/compat/index.md) tworzącemu aliasy dla bieżących importów, asercja pokrycia działa bezpośrednio na posiadanym pliku JSON.
+
+## Zdecyduj, co tak naprawdę testujesz
+
+Jakość tłumaczenia nie podlega weryfikacji w testach kodu. Żadna asercja nie oceni, czy język niemiecki brzmi naturalnie, a próby takiego testowania kończą się jedynie kodem zaśmieconym zahardkodowanymi ciągami znaków.
+
+To, co mechanicznie warto testować:
+
+| Warto testować                            | Nie warto testować                |
+| :---------------------------------------- | :-------------------------------- |
+| Każdy wymagany język posiada wartość      | Czy treść brzmi elegancko         |
+| Właściwy język trafia do komponentu       | Dokładna treść każdej etykiety    |
+| Liczba mnoga działa dla każdej kategorii  | Czy tłumacz wykonał swoje zadanie |
+| Języki RTL ustawiają kierunek i lustro    | Każdy ciąg w każdym języku        |
+| Sformatowane daty i liczby stosują locale | Wewnętrzna poprawność `Intl`      |
+
+Weryfikacja pokrycia powinna znajdować się w jednym teście opartym na danych, a nie w testach komponentów. Temat ten omawia artykuł [wykrywanie brakujących tłumaczeń](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/detecting_missing_translations.md); ten wpis skupia się na pozostałych kwestiach.
+
+## Renderuj wewnątrz providera i wyszukuj po roli
+
+Głównym wzorcem jest montowanie komponentu wewnątrz providera języka i wyszukiwanie po roli lub identyfikatorze testowym, a nie po treści.
+
+```tsx fileName="CartSummary.test.tsx"
+import { render, screen } from "@testing-library/react";
+import { IntlayerProvider } from "react-intlayer/client";
+import { CartSummary } from "./CartSummary";
+
+test("renderuje nagłówek podsumowania po francusku", () => {
+  render(
+    <IntlayerProvider locale="fr-FR">
+      <CartSummary />
+    </IntlayerProvider>
+  );
+
+  expect(screen.getByRole("heading")).toBeInTheDocument();
+});
+```
+
+Wyszukiwanie `getByRole("heading")` pozostaje odporne na zmiany w treści. `getByText("Récapitulatif")` psuje się przy pierwszej modyfikacji. Używaj dokładnego tekstu tylko wtedy, gdy sam ciąg znaków jest przedmiotem testu, co zdarza się rzadko.
+
+W przypadku atrybutów takich jak `aria-label` potrzebujesz czystego ciągu znaków, a nie węzła React. W React wpisy `useIntlayer` udostępniają do tego pole `.value`.
+
+## Parametryzuj testy między językami
+
+Jeden zestaw testów wykonywany dla każdego języka daje znacznie większą wartość niż osobny test dla każdego języka z osobna.
+
+```tsx fileName="direction.test.tsx"
+import { getHTMLTextDir } from "intlayer";
+import { render } from "@testing-library/react";
+import { IntlayerProvider } from "react-intlayer/client";
+
+describe.each(["en", "fr", "ja", "ar"])("locale %s", (locale) => {
+  it("renderuje bez powrotu do surowego klucza", () => {
+    const { container } = render(
+      <IntlayerProvider locale={locale}>
+        <CartSummary />
+      </IntlayerProvider>
+    );
+
+    // Wyrenderowany klucz oznacza, że pobranie wartości nie powiodło się.
+    expect(container.textContent).not.toMatch(/^[a-z]+(\.[a-z]+)+$/);
+  });
+
+  it("ustawia prawidłowy kierunek tekstu", () => {
+    expect(getHTMLTextDir(locale)).toBe(locale === "ar" ? "rtl" : "ltr");
+  });
+});
+```
+
+Pierwsza asercja to szybka i tania korzyść: jeśli pobranie wartości zawiedzie i biblioteka wyrenderuje klucz, DOM będzie zawierał strukturę w rodzaju `cart.summary.title`. Wychwytuje to całą klasę błędów bez podawania jakichkolwiek konkretnych fraz.
+
+## Pseudolokalizacja znajduje to, czego nie widzą katalogi
+
+Dodaj sztuczny język, który modyfikuje każdy ciąg znaków, na przykład przekształcając `Checkout` w `[!!! Çĥéçķöũţ !!!]`. Następnie wyrenderuj stronę w tym języku.
+
+Wszystko, co nadal wyświetla się w standardowym języku angielskim, zostało wpisane na sztywno w kodzie. Żaden audyt katalogów tego nie wykryje, ponieważ z perspektywy narzędzi ten ciąg po prostu nie istnieje. Nawiasy pełnią dodatkową funkcję: wydłużają tekst o około 30 procent, ujawniając błędy układu, zanim pojawią się w języku niemieckim.
+
+Najlepiej przeprowadzać to w formie testów wizualnych lub end-to-end zamiast testów jednostkowych, ponieważ błąd jest widoczny gołym okiem.
+
+## Liczba mnoga wymaga testu dla kategorii, a nie dla języka
+
+Błędy liczby mnogiej łatwo przeoczyć, ponieważ angielski ma tylko dwie formy i większość programistów sprawdza tylko je. Polski ma cztery, a arabski sześć.
+
+```ts fileName="plural.test.ts"
+// Arabski sprawdza zero, one, two, few, many, other.
+describe.each([0, 1, 2, 3, 11, 100])("liczba %i", (count) => {
+  it("tworzy niepusty ciąg znaków w języku arabskim", () => {
+    expect(formatItems(count, "ar")).not.toBe("");
+  });
+});
+```
+
+Wybieraj wartości liczbowe odpowiadające każdej kategorii CLDR dla najbardziej złożonego języka, zamiast sprawdzać wszędzie 1 i 2. `Intl.PluralRules` podpowiada, do której kategorii wpada dana liczba, dzięki czemu możesz wyznaczyć próbki bez zgadywania. Więcej szczegółów w [artykule o formacie wiadomości ICU](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/icu_message_format.md).
+
+## Pułapka snapshotów
+
+Snapshoty i i18n to złe połączenie. Snapshot zlokalizowanego komponentu utrwala każdy zawarty w nim tekst: gdy tłumacz poprawi literówkę w języku portugalskim, zielony test staje się czerwony, w pliku, którego recenzent nie jest w stanie zrozumieć. Po kilku takich razach ktoś uruchamia `-u` bez czytania diffa, a snapshoty tracą jakiekolwiek znaczenie.
+
+Jeśli chcesz używać snapshotów, wykonuj je tylko w jednym języku i traktuj jako kontrolę strukturalną, a nie treściową. Wszystko, co zależy od języka, powinno być weryfikowane jawnymi asercjami.
+
+## Testuj negocjację języka, a nie tylko renderowanie
+
+Najczęstszym błędem i18n na produkcji nie jest brakujący tekst. Jest nim wybór niewłaściwego języka: URL wskazuje `/fr/`, klient odczytuje `navigator.language` i powstaje konflikt.
+
+Testuj kolejność rozwiązywania języka bezpośrednio jako czystą funkcję, niezależnie od jakichkolwiek komponentów:
+
+```ts fileName="locale-resolution.test.ts"
+it("faworyzuje URL ponad zapisaną preferencję", () => {
+  expect(resolveLocale({ url: "/fr/about", stored: "de", header: "ja" })).toBe(
+    "fr"
+  );
+});
+
+it("wybiera nagłówek, gdy URL nie zawiera prefiksu", () => {
+  expect(resolveLocale({ url: "/about", stored: null, header: "ja" })).toBe(
+    "ja"
+  );
+});
+```
+
+To najbardziej wartościowy test i18n, którego brakuje w większości projektów, a nie wymaga on nawet środowiska DOM.
+
+## Co uruchamiać i gdzie
+
+- **Unit**: negocjacja języka, formatowania, kategorie liczby mnogiej. Szybkie, bez DOM.
+- **Komponenty**: jeden render w providerze na język, sprawdzający role i brak surowych kluczy.
+- **Pokrycie**: test oparty na danych weryfikujący brak brakujących wymaganych języków.
+- **Wizualne lub E2E**: przejście z pseudolokalizacją oraz strona RTL, ponieważ te błędy są wizualne.
+
+Utrzymuj pierwsze trzy w procesie CI przy każdym commicie. Ostatni punkt warto uruchamiać w nocnych kompilacjach.
+
+## Częste błędy
+
+- **Asercje na dosłowny tekst w każdym miejscu.** Skazuje zestaw testów na usunięcie w ciągu kilku miesięcy.
+- **Tworzenie snapshotów zlokalizowanych komponentów.** Tłumacze psują build, a recenzenci zatwierdzają bez czytania.
+- **Testowanie tylko domyślnego języka.** Jedynego, którego na pewno nie zabraknie.
+- **Testowanie tylko 1 i 2 dla liczb mnogich.** Pomija kategorie, których nie ma w angielskim.
+- **Mockowanie całej biblioteki i18n.** Wtedy testujesz jedynie to, czy twój mock zwraca ciągi znaków.
+- **Pomijanie testów negocjacji języka.** Najczęstsza awaria produkcyjna i najprostsza do przetestowania.
+
+## Warto przeczytać
+
+- [Testowanie zawartości: audyt CLI, programistyczne API i asercje UI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/testing.md)
+- [Wtyczka ESLint: wykrywanie zahardkodowanego tekstu i nieużywanych treści](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/eslint.md)
+- [Formatery i narzędzia językowe, w tym `getHTMLTextDir`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/formatters.md)
+- [Raporty wydajnościowe porównujące frameworki](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/benchmark/index.md)
+- [Adapter kompatybilności react-i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/compat/react-i18next.md)
+- [Jak wykrywać brakujące tłumaczenia](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/detecting_missing_translations.md)
+- [Format wiadomości ICU: liczby mnogie, select i szablony](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/icu_message_format.md)

package/blog/pl/intlayer_with_i18next.md

@@ -74,15 +74,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > flaga `--interactive` jest opcjonalna. Użyj `intlayer-cli init`, jeśli jesteś agentem AI.

package/blog/pl/intlayer_with_next-i18next.md

@@ -67,15 +67,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > flaga `--interactive` jest opcjonalna. Użyj `intlayer-cli init`, jeśli jesteś agentem AI.

package/blog/pl/intlayer_with_next-intl.md

@@ -69,15 +69,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > flaga `--interactive` jest opcjonalna. Użyj `intlayer-cli init`, jeśli jesteś agentem AI.

package/blog/pl/intlayer_with_react-i18next.md

@@ -68,15 +68,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > flaga `--interactive` jest opcjonalna. Użyj `intlayer-cli init`, jeśli jesteś agentem AI.

package/blog/pl/intlayer_with_react-intl.md

@@ -66,15 +66,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > flaga `--interactive` jest opcjonalna. Użyj `intlayer-cli init`, jeśli jesteś agentem AI.

package/blog/pl/intlayer_with_vue-i18n.md

@@ -68,15 +68,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > flaga `--interactive` jest opcjonalna. Użyj `intlayer-cli init`, jeśli jesteś agentem AI.

package/blog/pl/is_i18next_outdated.md

@@ -0,0 +1,315 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: Czy i18next jest przestarzały w 2026 roku?
+description: i18next napędza miliony stron internetowych, ale jego architektura runtime z 2011 roku zaczyna odstawać od standardów. Spojrzenie na rozmiar bundle, ograniczenia tree-shakingu i spowolniony rozwój.
+keywords:
+  - i18next
+  - react-i18next
+  - next-i18next
+  - Intlayer
+  - Internacjonalizacja
+  - i18n
+  - Rozmiar bundle
+  - Blog
+slugs:
+  - blog
+  - is-i18next-outdated
+author: aymericzip
+---
+
+# Czy i18next jest przestarzały w 2026 roku?
+
+`i18next` zadebiutował w 2011 roku, na długo przed tym, jak komponenty React, bundler Webpack czy TypeScript stały się standardem. Zdobył dominację w ekosystemie dzięki elastyczności i powszechności, zyskując wtyczki dla niemal każdego stosu technologicznego oraz gotowe odpowiedzi na StackOverflow na niemal każdy błąd.
+
+Projekt nie jest porzucony, łatki pojawiają się regularnie. Istnieje jednak zasadnicza różnica między utrzymywaniem starszego silnika przy życiu a aktywnym rozwojem w zgodzie ze współczesną architekturą frontendu.
+
+W ostatnich latach frontend przesunął się w stronę kompilacji w czasie budowania, React Server Components (RSC), agresywnego tree-shakingu i procesów opartych na AI. Trzon i18next pozostaje tym samym, czym był dekadę temu: singletonem w czasie wykonywania, dopasowującym klucze tekstowe po stronie klienta.
+
+<TOC/>
+
+## Kluczowe wnioski
+
+**Tryb konserwacji:**
+
+W minionym roku `next-i18next` odnotował ~63 commity (średnio jeden w tygodniu), a `react-i18next` ~157, głównie w zakresie aktualizacji zależności i drobnych poprawek.
+
+**Wysoki narzut runtime:**
+
+`react-i18next` i `next-i18next` dodają ~17–18 KB gzipped (~60 KB po minifikacji) przed wyrenderowaniem pojedynczego przetłumaczonego słowa, czyli prawie 4x więcej niż `next-intlayer` (~4.7 KB).
+
+**Poważny wyciek danych tłumaczeń:**
+
+W domyślnych konfiguracjach statycznych aż do **89.8%** danych lokalizacyjnych przesyłanych na stronę dotyczy innych podstron lub nieużywanych języków.
+
+**Niemożliwy tree-shaking:**
+
+Dynamiczne wywołania w stylu `t("home.hero.title")` uniemożliwiają analizę przez bundlery, co zmusza do dołączania całych plików JSON do pakietu klienta.
+
+**Uwarunkowania biznesowe:**
+
+Twórcy rozwijają platformę Locize. Zbudowanie bezpłatnego, lokalnego potoku tłumaczeń AI bezpośrednio w CLI byłoby bezpośrednią konkurencją dla ich głównego źródła przychodów.
+
+## Utrzymanie vs. aktywna ewolucja
+
+Liczba gwiazdek na GitHubie odzwierciedla historyczną popularność, a nie aktualną dynamikę architektoniczną.
+
+| Repozytorium            | Gwiazdki                                                                                                                                                   | Wszystkie commity                                                                                                                                                       | Commity / rok                                                                                                                                                          | Ostatni commit                                                                                                                                   |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `i18next/i18next`       | [![stars](https://img.shields.io/github/stars/i18next/i18next?style=for-the-badge&label=stars)](https://github.com/i18next/i18next/stargazers)             | [![commits](https://img.shields.io/github/commit-activity/t/i18next/i18next?style=for-the-badge&label=commits)](https://github.com/i18next/i18next/commits)             | [![yearly](https://img.shields.io/github/commit-activity/y/i18next/i18next?style=for-the-badge&label=%2Fyear)](https://github.com/i18next/i18next/commits)             | [![last](https://img.shields.io/github/last-commit/i18next/i18next?style=for-the-badge)](https://github.com/i18next/i18next/commits)             |
+| `i18next/react-i18next` | [![stars](https://img.shields.io/github/stars/i18next/react-i18next?style=for-the-badge&label=stars)](https://github.com/i18next/react-i18next/stargazers) | [![commits](https://img.shields.io/github/commit-activity/t/i18next/react-i18next?style=for-the-badge&label=commits)](https://github.com/i18next/react-i18next/commits) | [![yearly](https://img.shields.io/github/commit-activity/y/i18next/react-i18next?style=for-the-badge&label=%2Fyear)](https://github.com/i18next/react-i18next/commits) | [![last](https://img.shields.io/github/last-commit/i18next/react-i18next?style=for-the-badge)](https://github.com/i18next/react-i18next/commits) |
+| `i18next/next-i18next`  | [![stars](https://img.shields.io/github/stars/i18next/next-i18next?style=for-the-badge&label=stars)](https://github.com/i18next/next-i18next/stargazers)   | [![commits](https://img.shields.io/github/commit-activity/t/i18next/next-i18next?style=for-the-badge&label=commits)](https://github.com/i18next/next-i18next/commits)   | [![yearly](https://img.shields.io/github/commit-activity/y/i18next/next-i18next?style=for-the-badge&label=%2Fyear)](https://github.com/i18next/next-i18next/commits)   | [![last](https://img.shields.io/github/last-commit/i18next/next-i18next?style=for-the-badge)](https://github.com/i18next/next-i18next/commits)   |
+| `aymericzip/intlayer`   | [![stars](https://img.shields.io/github/stars/aymericzip/intlayer?style=for-the-badge&label=stars)](https://github.com/aymericzip/intlayer/stargazers)     | [![commits](https://img.shields.io/github/commit-activity/t/aymericzip/intlayer?style=for-the-badge&label=commits)](https://github.com/aymericzip/intlayer/commits)     | [![yearly](https://img.shields.io/github/commit-activity/y/aymericzip/intlayer?style=for-the-badge&label=%2Fyear)](https://github.com/aymericzip/intlayer/commits)     | [![last](https://img.shields.io/github/last-commit/aymericzip/intlayer?style=for-the-badge)](https://github.com/aymericzip/intlayer/commits)     |
+
+Aktywność w ostatnich dwunastu miesiącach:
+
+| Projekt         | Wszystkie commity | Ostatnie 12 miesięcy | Obszar koncentracji                   |
+| --------------- | ----------------- | -------------------- | ------------------------------------- |
+| `next-i18next`  | 1 311             | **63**               | Zgodność z Next.js i poprawki błędów  |
+| `react-i18next` | 1 988             | **157**              | Typowanie i utrzymanie                |
+| `i18next` core  | 2 626             | **259**              | Drobne łatki                          |
+| Intlayer        | 7 156             | **4 343**            | Kompilator, narzędzia IDE i silnik AI |
+
+[![Star History Chart](https://api.star-history.com/chart?repos=i18next%2Fi18next%2Ci18next%2Freact-i18next%2Ci18next%2Fnext-i18next%2Caymericzip%2Fintlayer&type=date&legend=top-left)](https://www.star-history.com/#i18next/i18next&i18next/react-i18next&i18next/next-i18next&aymericzip/intlayer)
+
+Mniejsza biblioteka może być dojrzała i stabilna. Jednak ekosystem i18n stale się rozwija: współczesne bundlery eliminują nieużywane treści już podczas budowania, modele LLM automatyzują tłumaczenia w CI, a edytory polegają na serwerach językowych (LSP) i agentach AI. Architektura i18next oparta na runtime utrudnia korzystanie z tych innowacji.
+
+## Pomiar narzutu na bundle
+
+<I18nBenchmark framework="tanstack" vertical/>
+
+<ClickToOpenIframe
+src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-tanstack.md"
+width="100%"
+height="600px"
+style="border:none;"
+/>
+
+> Pomiary wykonane na produkcyjnym buildzie z 10 trasami i 10 językami przy włączonej kompresji gzip. Szczegóły w [raporcie benchmarku i18n](https://intlayer.org/pl/doc/benchmark).
+
+### Bazowy narzut biblioteki
+
+Waga przed załadowaniem jakichkolwiek przetłumaczonych tekstów:
+
+| Biblioteka             | Gzipped    | Zminifikowane |
+| ---------------------- | ---------- | ------------- |
+| `next-i18next@16.0.5`  | 17.8 KB    | 61.2 KB       |
+| `react-i18next@17.0.2` | 17.3 KB    | 59.8 KB       |
+| `intlayer@8.7.12`      | **4.7 KB** | **12.8 KB**   |
+
+### Waga strony i wyciek danych
+
+Przetestowano w środowisku React / TanStack Start (strategia statyczna):
+
+| Biblioteka            | Śr. JS / str. (gz) | Wyciek języków | Wyciek innych stron | Śr. komponent (gz) | Hydratacja  |
+| --------------------- | ------------------ | -------------- | ------------------- | ------------------ | ----------- |
+| `react-i18next`       | 180.3 KB           | **50.0%**      | **89.8%**           | 24.3 KB            | 85.1 ms     |
+| Intlayer              | **127.8 KB**       | 50.0%          | **0.8%**            | **7.1 KB**         | **24.1 ms** |
+| Intlayer (scoped dyn) | **118.1 KB**       | **0.0%**       | **0.8%**            | **4.6 KB**         | 23.7 ms     |
+
+W Next.js:
+
+| Biblioteka      | Śr. JS / str. (gz) | Wyciek innych stron | Śr. komponent (gz) |
+| --------------- | ------------------ | ------------------- | ------------------ |
+| Baza (bez i18n) | 150.8 KB           | 0.0%                | 0.7 KB             |
+| `next-i18next`  | **227.5 KB**       | **89.8%**           | 24.5 KB            |
+| `next-intlayer` | **152.1 KB**       | **0.0%**            | **7.2 KB**         |
+
+### Główne wnioski
+
+**Waga strony:**
+
+W Next.js `next-i18next` dodaje **76.7 KB gzipped** do projektu bazowego (+50%). `next-intlayer` dodaje jedynie 1.3 KB.
+
+**Wyciek danych:**
+
+Domyślnie niemal **90% treści tłumaczeń** przesyłanych do danej trasy dotyczy innych podstron. Ręczne dzielenie na namespace'y jest uciążliwe i sprzyja błędom.
+
+**Opóźnienie hydratacji:**
+
+Komponenty z `react-i18next` potrzebowały **85 ms** na hydratację w porównaniu do **24 ms** w Intlayer. Przekazywanie dużych struktur JSON spowalnia interaktywność.
+
+## Dlaczego i18next jest ciężki?
+
+### Rozrost funkcji w czasie wykonywania
+
+Działanie wyłącznie w przeglądarce wymusza przesyłanie wszystkich mechanizmów z góry: interpolacji, reguł liczby mnogiej, kontekstów, formaterów i szyny zdarzeń. Nawet podstawowy tekst niesie ze sobą pełen silnik.
+
+### Dynamiczne klucze blokują tree-shaking
+
+Ponieważ ciąg `"hero.title"` jest interpretowany dynamicznie w runtime, bundlery nie wiedzą, które klucze są realnie używane. Nieużywane teksty pozostają w paczce.
+
+<Tabs defaultTab="intlayer" group="techno">
+  <Tab label="i18next" value="i18next">
+
+```tsx fileName="Component.tsx"
+const { t } = useTranslation("home");
+
+return <h1>{t("hero.title")}</h1>;
+```
+
+  </Tab>
+  <Tab label="Intlayer" value="intlayer">
+
+```tsx fileName="Hero.tsx"
+const { title } = useIntlayer("hero");
+
+return <h1>{title}</h1>;
+```
+
+  </Tab>
+</Tabs>
+
+[Kompilator Intlayer](https://intlayer.org/pl/doc/compiler) analizuje, co faktycznie jest wykorzystywane w `Hero.tsx`, i eliminuje niepotrzebne pola przed utworzeniem plików klienta. Zobacz [optymalizację bundle](https://intlayer.org/pl/doc/concept/bundle-optimization).
+
+## Doświadczenie programisty
+
+### Rozproszony JSON vs. ko-lokacja
+
+W i18next tłumaczenia znajdują się w osobnych katalogach JSON z dala od komponentów. Intlayer umieszcza deklaracje treści tuż obok kodu widoków:
+
+<Tabs defaultTab="intlayer" group="techno">
+  <Tab label="i18next" value="i18next">
+
+```json fileName="locales/en/hero.json"
+{
+  "title": "Ship in every language"
+}
+```
+
+```json fileName="locales/pl/hero.json"
+{
+  "title": "Wdrażaj w każdym języku"
+}
+```
+
+```tsx fileName="Hero.tsx"
+import { useTranslation } from "react-i18next";
+
+export const Hero = () => {
+  const { t } = useTranslation("hero");
+  return <h1>{t("title")}</h1>;
+};
+```
+
+  </Tab>
+  <Tab label="Intlayer" value="intlayer">
+
+```ts fileName="hero.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "hero",
+  content: {
+    title: t({
+      en: "Ship in every language",
+      pl: "Wdrażaj w każdym języku",
+    }),
+  },
+} satisfies Dictionary;
+```
+
+```tsx fileName="Hero.tsx"
+import { useIntlayer } from "react-intlayer";
+
+export const Hero = () => {
+  const { title } = useIntlayer("hero");
+  return <h1>{title}</h1>;
+};
+```
+
+  </Tab>
+</Tabs>
+
+Gdy przenosisz lub usuwasz `Hero.tsx`, jego plik treści jest przenoszony lub usuwany wraz z nim.
+
+### Autouzupełnianie vs. rygorystyczne typowanie
+
+Rozszerzenie `CustomTypeOptions` zapewnia autouzupełnianie w edytorze, ale nie gwarantuje kompletności tłumaczeń. Usunięcie klucza z `pl/home.json` nie zatrzyma procesu budowania, a jedynie wywoła fallback w runtime.
+
+Intlayer wyprowadza typy wprost z deklaracji zawartości, a tryb [`strictMode`](https://intlayer.org/pl/doc/concept/configuration) sprawia, że brak tłumaczenia powoduje błąd kompilacji.
+
+### Porównanie narzędzi
+
+| Funkcjonalność              | Ekosystem i18next    | Intlayer                                                                   |
+| --------------------------- | -------------------- | -------------------------------------------------------------------------- |
+| **Rozszerzenie VS Code**    | Tylko zewnętrzne     | ✅ [Oficjalne rozszerzenie](https://intlayer.org/pl/doc/vs-code-extension) |
+| **Language Server (LSP)**   | ❌ Brak              | ✅ [Dedykowany LSP](https://intlayer.org/pl/doc/lsp)                       |
+| **Serwer MCP (dla AI)**     | ❌ Brak              | ✅ [Zintegrowany serwer MCP](https://intlayer.org/pl/doc/mcp-server)       |
+| **Umiejętności agentów**    | ❌ Brak              | ✅ [Gotowe skille](https://intlayer.org/pl/doc/agent_skills)               |
+| **Wizualny CMS in-context** | Locize (Płatny SaaS) | ✅ [Darmowy & Open Source](https://intlayer.org/pl/doc/concept/editor)     |
+
+## Tłumaczenia i model biznesowy Locize
+
+Locize to komercyjna usługa prowadzona przez twórców i18next. Zrównoważone finansowanie open source jest kluczowe, ale rodzi pewien konflikt: projekt zarabiający na zewnętrznej platformie tłumaczeniowej nie ma motywacji, by dodać do swojego CLI darmowe narzędzie do lokalnego tłumaczenia AI.
+
+Intlayer stawia na otwarte podejście:
+
+- [`intlayer fill`](https://intlayer.org/pl/doc/concept/auto-fill) uzupełnia brakujące teksty w terminalu lub CI przy użyciu Twoich kluczy API OpenAI, Anthropic, Mistral lub Gemini.
+- [Intlayer CMS](https://intlayer.org/pl/doc/concept/cms) jest projektem open source i można go uruchomić lokalnie przez Docker Compose.
+- Kompilator, CLI, edytor i CMS są udostępniane na licencji Apache 2.0.
+
+## Gdzie i18next nadal ma rację bytu?
+
+<AccordionGroup>
+<Accordion header="Dojrzałe, stabilne projekty">
+
+Jeśli aplikacja działa bez zakłóceń, a rozmiar pakietu nie stanowi bariery, natychmiastowa migracja nie jest konieczna.
+
+</Accordion>
+<Accordion header="Specyficzne platformy">
+
+Szeroka baza pluginów i18next wspiera konfiguracje (Electron, starsze aplikacje jQuery, niestandardowe mostki natywne), których nowsze kompilatory bezpośrednio nie obsługują.
+
+</Accordion>
+<Accordion header="Obszerna baza wiedzy społeczności">
+
+Wieloletni dorobek na StackOverflow i GitHubie pomaga w rozwiązywaniu nietypowych problemów.
+
+</Accordion>
+</AccordionGroup>
+
+## Jak ulepszyć istniejącą konfigurację i18next?
+
+Intlayer oferuje gotowe pakiety kompatybilności, które zachowują dokładnie te same sygnatury funkcji bibliotek i18next (`i18next`, `react-i18next` oraz `next-i18next`). Nie musisz przepisywać komponentów, aby zyskać korzyści z nowoczesnej architektury opartej na kompilatorze.
+
+Konfiguracja sprowadza się do jednego polecenia:
+
+```bash packageManager="npm"
+npx intlayer init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer init --interactive
+```
+
+To interaktywne CLI:
+
+1. Instaluje pakiet kompatybilności `@intlayer/i18next`.
+2. Konfiguruje aliasy bundlera, dzięki czemu dotychczasowe importy (`useTranslation`, `Trans`, `t`) odwołują się do Intlayer, co pozwala usunąć starą bibliotekę z `package.json`.
+3. Natychmiast podłącza wsparcie Language Servera (LSP) w edytorze, optymalizację pakietu na etapie kompilacji (pełny tree-shaking) i lokalne procesy tłumaczenia przez AI.
+
+Szczegółowe instrukcje znajdziesz w naszych poradnikach:
+
+- **Warstwy zgodności:** Zachowaj dotychczasowy kod z adapterami dla [i18next](https://intlayer.org/pl/doc/compatibility/i18next), [react-i18next](https://intlayer.org/pl/doc/compatibility/react-i18next) oraz [next-i18next](https://intlayer.org/pl/doc/compatibility/next-i18next).
+- **Migracja katalogów:** Przekonwertuj pliki JSON w typowane słowniki: [z i18next](https://intlayer.org/pl/doc/migration/i18next), [z react-i18next](https://intlayer.org/pl/doc/migration/react-i18next) lub [z next-i18next](https://intlayer.org/pl/doc/migration/next-i18next).
+- **Podejście hybrydowe:** Zachowaj runtime i18next, jednocześnie [wykorzystując Intlayer z i18next](https://intlayer.org/pl/blog/intlayer-with-i18next) do typowania i automatycznego tłumaczenia plików.
+
+Przetestuj swoją stronę darmowym [skanerem SEO i18n](https://intlayer.org/i18n-seo-scanner):
+
+<ClickToOpenIframe src="https://intlayer.org/i18n-seo-scanner" width="100%" height="600px" style="border:none;"/>
+
+## Przydatne artykuły
+
+- [Benchmark Next.js i18n: pełna analiza wydajności](https://intlayer.org/pl/doc/benchmark/nextjs)
+- [react-i18next vs react-intl vs Intlayer](https://intlayer.org/pl/blog/react-i18next-vs-react-intl-vs-intlayer)
+- [Czy next-intl jest przestarzały w 2026 roku?](https://intlayer.org/pl/blog/is-next-intl-outdated)
+- [Kompilacja a deklaratywna architektura i18n](https://intlayer.org/pl/blog/compiler-vs-declarative-i18n)