@intlayer/docs 8.7.4 → 8.7.5

package/docs/pl/benchmark/nextjs.md

@@ -0,0 +1,227 @@
+---
+createdAt: 2026-04-20
+updatedAt: 2026-04-21
+title: Najlepsze rozwiązanie i18n dla Next.js w 2026 r. - Raport Benchmark
+description: Porównaj biblioteki internacjonalizacji (i18n) dla Next.js, takie jak next-intl, next-i18next i Intlayer. Szczegółowy raport wydajności dotyczący rozmiaru pakietu, wycieków i reaktywności.
+keywords:
+  - benchmark
+  - i18n
+  - intl
+  - nextjs
+  - wydajność
+  - intlayer
+slugs:
+  - doc
+  - benchmark
+  - nextjs
+author: Aymeric PINEAU
+applicationTemplate: https://github.com/intlayer-org/benchmark-i18n
+history:
+  - version: 8.7.5
+    date: 2026-01-06
+    changes: "Inicjalizacja benchmarka"
+---
+
+# Biblioteki i18n dla Next.js — Raport Benchmark 2026
+
+Ta strona to raport z benchmarku rozwiązań i18n w Next.js.
+
+## Spis Treści
+
+<Toc/>
+
+## Interaktywny Benchmark
+
+<I18nBenchmark framework="nextjs" vertical/>
+
+## Referencja wyników:
+
+<iframe 
+  src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-nextjs.md" 
+  width="100%" 
+  height="600px"
+  style="border:none;">
+</iframe>
+
+> https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-nextjs.md
+
+Zobacz pełne repozytorium benchmarka [tutaj](https://github.com/intlayer-org/benchmark-i18n).
+
+## Wprowadzenie
+
+Biblioteki internacjonalizacji mają ogromny wpływ na Twoją aplikację. Głównym ryzykiem jest ładowanie treści dla każdej strony i każdego języka, gdy użytkownik odwiedza tylko jedną stronę.
+
+W miarę rozwoju aplikacji rozmiar pakietu może rosnąć wykładniczo, co może zauważalnie obniżyć wydajność.
+
+Jako przykład: w najgorszych przypadkach, po internacjonalizacji Twoja strona może stać się niemal 4 razy większa.
+
+Innym skutkiem bibliotek i18n jest wolniejszy rozwój. Przekształcanie komponentów w wielojęzyczne treści w wielu językach jest czasochłonne.
+
+Ponieważ problem jest trudny, istnieje wiele rozwiązań — niektóre koncentrują się na DX (Developer Experience), inne na wydajności lub skalowalności itd.
+
+Intlayer stara się optymalizować we wszystkich tych wymiarach.
+
+## Przetestuj swoją aplikację
+
+Aby ujawnić te problemy, zbudowałem darmowy skaner, który możesz wypróbować [tutaj](https://intlayer.org/i18n-seo-scanner).
+
+<iframe src="https://intlayer.org/i18n-seo-scanner" width="100%" height="600px" style="border:none;"/>
+
+## Problem
+
+Istnieją dwa główne sposoby na ograniczenie wpływu aplikacji wielojęzycznej na rozmiar pakietu:
+
+- Podział plików JSON (lub treści) na pliki / zmienne / przestrzenie nazw (namespaces), aby bundler mógł usunąć (tree-shake) nieużywaną treść dla danej strony.
+- Dynamiczne ładowanie treści strony tylko w języku użytkownika.
+
+Ograniczenia techniczne tych podejść:
+
+**Ładowanie dynamiczne**
+
+Nawet gdy deklarujesz ścieżki typu `[locale]/page.tsx`, korzystając z Webpacka lub Turbopacka, i nawet jeśli zdefiniowano `generateStaticParams`, bundler nie traktuje `locale` jako stałej statycznej. Oznacza to, że może on pobrać treść dla wszystkich języków do każdej strony. Głównym sposobem na ograniczenie tego jest ładowanie treści poprzez import dynamiczny (np. `import('./locales/${locale}.json')`).
+
+To, co dzieje się w czasie budowania (build time), to fakt, że Next.js generuje jeden pakiet JS na lokalizację (np. `./locales_pl_12345.js`). Po wysłaniu strony do klienta, gdy strona jest uruchamiana, przeglądarka wykonuje dodatkowe żądanie HTTP o potrzebny plik JS (np. `./locales_pl_12345.js`).
+
+> Innym sposobem na rozwiązanie tego samego problemu jest użycie `fetch()` do dynamicznego ładowania plików JSON. Tak działa `Tolgee`, gdy pliki JSON znajdują się w `/public`, lub `next-translate`, który polega na `getStaticProps` do ładowania treści. Przepływ jest taki sam: przeglądarka wysyła dodatkowe żądanie HTTP, aby załadować zasób.
+
+**Podział treści (Content splitting)**
+
+Jeśli używasz składni typu `const t = useTranslation()` + `t('moj-obiekt.moj-podobiekt.moj-klucz')`, cały plik JSON musi zazwyczaj znajdować się w pakiecie, aby biblioteka mogła go przeanalizować i rozwiązać klucz. Duża część tej treści jest wysyłana nawet wtedy, gdy nie jest używana na stronie.
+
+Aby to złagodzić, niektóre biblioteki proszą o zadeklarowanie na poziomie strony, które przestrzenie nazw należy załadować — np. `next-i18next`, `next-intl`, `lingui`, `next-translate`, `next-international`.
+
+Z kolei `Paraglide` dodaje dodatkowy krok przed budowaniem, aby zamienić pliki JSON na proste symbole, takie jak `const en_my_var = () => 'moja wartosc'`. Teoretycznie umożliwia to usuwanie (tree-shaking) nieużywanej treści na stronie. Jak zobaczymy, ta metoda wciąż ma swoje wady.
+
+Wreszcie, `Intlayer` stosuje optymalizację w czasie budowania, dzięki czemu `useIntlayer('moj-klucz')` jest zastępowany bezpośrednio odpowiednią treścią.
+
+## Metodologia
+
+W tym benchmarku porównaliśmy następujące biblioteki:
+
+- `Base App` (Brak biblioteki i18n)
+- `next-intlayer` (v8.7.5)
+- `next-i18next` (v16.0.5)
+- `next-intl` (v4.9.1)
+- `@lingui/core` (v5.3.0)
+- `next-translate` (v3.1.2)
+- `next-international` (v1.3.1)
+- `@inlang/paraglide-js` (v2.15.1)
+- `tolgee` (v7.0.0)
+- `@lingo.dev/compiler` (v0.4.0)
+- `wuchale` (v0.22.11)
+- `gt-next` (v6.16.5)
+
+Użyłem `Next.js` w wersji `16.2.4` z App Routerem.
+
+Zbudowałem wielojęzyczną aplikację z **10 stronami** i **10 językami**.
+
+Porównałem **cztery strategie ładowania**:
+
+| Strategia                | Brak przestrzeni nazw (globalna)                  | Z przestrzeniami nazw (scoped)                                                   |
+| :----------------------- | :------------------------------------------------ | :------------------------------------------------------------------------------- |
+| **Ładowanie statyczne**  | **Static**: Wszystko w pamięci przy starcie.      | **Scoped static**: Podział na przestrzenie nazw; wszystko ładowane przy starcie. |
+| **Ładowanie dynamiczne** | **Dynamic**: Ładowanie na żądanie na lokalizację. | **Scoped dynamic**: Szczegółowe ładowanie na przestrzeń nazw i lokalizację.      |
+
+## Podsumowanie strategii
+
+- **Static**: Prosta; brak opóźnień sieciowych po początkowym załadowaniu. Minus: duży rozmiar pakietu.
+- **Dynamic**: Redukuje początkową wagę (lazy-loading). Idealna w przypadku wielu lokalizacji.
+- **Scoped static**: Utrzymuje porządek w kodzie (separacja logiczna) bez skomplikowanych dodatkowych żądań sieciowych.
+- **Scoped dynamic**: Najlepsze podejście pod kątem dzielenia kodu (code splitting) i wydajności. Minimalizuje zużycie pamięci, ładując tylko to, czego potrzebuje bieżący widok i aktywna lokalizacja.
+
+### Co mierzyłem:
+
+Uruchomiłem tę samą wielojęzyczną aplikację w prawdziwej przeglądarce dla każdego stosu technologicznego, a następnie zanotowałem, co faktycznie zostało wysłane przez sieć i ile czasu zajęły operacje. Rozmiary są podawane **po normalnej kompresji internetowej**, ponieważ jest to bliższe temu, co faktycznie pobierają użytkownicy.
+
+- **Rozmiar biblioteki internacjonalizacji**: Po spakowaniu, tree-shakingu i minifikacji, rozmiar biblioteki i18n to rozmiar kodu dostawców (np. `NextIntlClientProvider`) + hooków (np. `useTranslations`) w pustym komponencie. Nie obejmuje ładowania plików tłumaczeń. Odpowiada na pytanie, jak "droga" jest biblioteka, zanim Twoja treść znajdzie się w projekcie.
+
+- **JavaScript na stronę**: Dla każdej trasy benchmarku, ile skryptów przeglądarka pobiera podczas tej wizyty, uśrednione dla wszystkich stron w zestawie (i we wszystkich lokalizacjach). Ciężkie strony to wolne strony.
+
+- **Wyciek z innych lokalizacji (Leakage)**: To treść tej samej strony, ale w innym języku, która została omyłkowo załadowana na badanej stronie. Treść ta jest zbędna i należy jej unikać (np. treść strony `/fr/about` w pakiecie strony `/en/about`).
+
+- **Wyciek z innych ścieżek**: Ta sama idea dla **innych ekranów** w aplikacji: czy ich teksty są dołączone, gdy otworzyłeś tylko jedną stronę (np. treść strony `/en/about` w pakiecie strony `/en/contact`). Wysoki wynik sugeruje słaby podział lub zbyt szerokie pakiety.
+
+- **Średni rozmiar pakietu komponentu**: Typowe elementy interfejsu są mierzone **pojedynczo**, zamiast ukrywać się wewnątrz jednej gigantycznej liczby dla aplikacji. Pokazuje to, czy internacjonalizacja po cichu „pompuje” codzienne komponenty. Na przykład, jeśli Twój komponent renderuje się ponownie, załaduje wszystkie te dane z pamięci. Dołączanie gigantycznego pliku JSON do dowolnego komponentu jest jak podłączanie wielkiego magazynu nieużywanych danych, który spowolni wydajność Twoich komponentów.
+
+- **Responsywność zmiany języka**: Przełączam język za pomocą własnego mechanizmu aplikacji i mierzę czas, aż strona wyraźnie się przełączy — to, co zauważyłby użytkownik, a nie mikrokrok laboratoryjny.
+
+- **Praca renderowania po zmianie języka**: Bardziej szczegółowa analiza: ile wysiłku kosztowało interfejs ponowne odrysowanie dla nowego języka po rozpoczęciu zmiany. Przydatne, gdy „odczuwalny” czas i koszt frameworka się różnią.
+
+- **Początkowy czas ładowania strony**: Od nawigacji do momentu, w którym przeglądarka uzna stronę za w pełni załadowaną dla testowanych przeze mnie scenariuszy. Dobre do porównywania „zimnych startów” (cold starts).
+
+- **Czas hydratacji (Hydration)**: Gdy aplikacja to udostępnia, ile czasu klient spędza na zamianie kodu HTML z serwera w coś, co można faktycznie kliknąć. Myślnik w tabelach oznacza, że dana implementacja nie dostarczyła wiarygodnej wartości hydratacji w tym benchmarku.
+
+## Szczegóły wyników
+
+### 1 — Rozwiązania, których należy unikać
+
+Należy wyraźnie unikać niektórych rozwiązań, takich jak `gt-next` czy `lingo.dev`. Łączą one uzależnienie od dostawcy (vendor lock-in) z zaśmiecaniem bazy kodu. Mimo wielu godzin spędzonych na próbach ich wdrożenia, nigdy nie udało mi się sprawić, by działały poprawnie — ani w TanStack Start, ani w Next.js.
+
+Napotkane problemy:
+
+**(General Translation)** (`gt-next@6.16.5`):
+
+- W przypadku aplikacji o rozmiarze 110 KB, `gt-react` dodaje ponad 440 KB ekstra.
+- Komunikat `Quota Exceeded, please upgrade your plan` przy pierwszej próbie budowania z General Translation.
+- Tłumaczenia nie są renderowane; otrzymuję błąd `Error: <T> used on the client-side outside of <GTProvider>`, co wydaje się być błędem w bibliotece.
+- Podczas wdrażania **gt-tanstack-start-react** napotkałem również [problem](https://github.com/generaltranslation/gt/issues/1210#event-24510646961) z biblioteką: błąd `does not provide an export named 'printAST' - @formatjs/icu-messageformat-parser`, który powodował awarię aplikacji. Po zgłoszeniu tego problemu opiekun naprawił go w ciągu 24 godzin.
+- Biblioteka blokuje statyczne renderowanie stron Next.js.
+
+**(Lingo.dev)** (`@lingo.dev/compiler@0.4.0`):
+
+- Przekroczenie limitu AI, co całkowicie blokuje budowanie — nie można zatem wdrożyć aplikacji na produkcję bez płacenia.
+- Kompilator pomijał niemal 40% przetłumaczonej treści. Musiałem przepisać wszystkie struktury `.map` na płaskie bloki komponentów, aby go uruchomić.
+- Ich CLI jest zabugowane i miało tendencję do resetowania pliku konfiguracyjnego bez powodu.
+- Podczas budowania całkowicie wymazywało wygenerowane pliki JSON, gdy dodawana była nowa treść. W rezultacie kilka kluczy mogło wymazać ponad 300 istniejących kluczy.
+
+### 2 — Rozwiązania eksperymentalne
+
+**(Wuchale)** (`wuchale@0.22.11`):
+
+Idea stojąca za `Wuchale` jest interesująca, ale nie jest to jeszcze opłacalne rozwiązanie. Napotkałem problemy z reaktywnością i musiałem wymusić ponowne renderowanie dostawcy, aby aplikacja działała. Dokumentacja jest również dość niejasna, co utrudnia wdrożenie.
+
+**(Paraglide)** (`@inlang/paraglide-js@2.15.1`):
+
+`Paraglide` oferuje innowacyjne i przemyślane podejście. Mimo to w tym benchmarku reklamowany tree-shaking nie zadziałał w moich konfiguracjach Next.js ani TanStack Start. Przepływ pracy i DX są bardziej złożone niż w innych opcjach.
+Osobiście nie podoba mi się konieczność regenerowania plików JS przed każdym przesłaniem kodu (push), co stwarza ciągłe ryzyko konfliktów scalania (merge conflicts) przy Pull Requestach. Narzędzie wydaje się również bardziej skoncentrowane na Vite niż na Next.js.
+Wreszcie, w porównaniu z innymi rozwiązaniami, Paraglide nie używa magazynu (np. React context) do pobierania bieżącej lokalizacji w celu renderowania treści. Dla każdego przeanalizowanego węzła żąda lokalizacji z localStorage / cookie itp. Prowadzi to do wykonywania niepotrzebnej logiki, co wpływa na reaktywność komponentu.
+
+### 3 — Akceptowalne rozwiązania
+
+**(Tolgee)** (`tolgee@7.0.0`):
+
+`Tolgee` rozwiązuje wiele z wymienionych wcześniej problemów. Uznałem jednak, że trudniej go wdrożyć niż podobne narzędzia. Nie zapewnia on bezpieczeństwa typów (type safety), co utrudnia również wyłapywanie brakujących kluczy w czasie kompilacji. Musiałem opakować funkcje Tolgee we własne funkcje, aby dodać wykrywanie brakujących kluczy.
+
+**(Next Intl)** (`next-intl@4.9.1`):
+
+`next-intl` to obecnie najmodniejsza opcja i ta, którą agenci AI forsują najbardziej, ale moim zdaniem niesłusznie. Rozpoczęcie pracy jest łatwe. W praktyce optymalizacja pod kątem ograniczania wycieków jest złożona. Połączenie dynamicznego ładowania + przestrzeni nazw + typów TypeScript bardzo spowalnia rozwój. Pakiet jest również dość ciężki (~13 KB dla `NextIntlClientProvider` + `useTranslations`, co stanowi ponad 2-krotność `next-intlayer`). **next-intl** blokował niegdyś statyczne renderowanie stron Next.js. Udostępnia on funkcję pomocniczą o nazwie `setRequestLocale()`. Wydaje się, że zostało to częściowo rozwiązane w przypadku scentralizowanych plików, takich jak `en.json` / `fr.json`, ale statyczne renderowanie wciąż przestaje działać, gdy treść jest podzielona na przestrzenie nazw, takie jak `en/shared.json` / `fr/shared.json` / `es/shared.json`.
+
+**(Next I18next)** (`next-i18next@16.0.5`):
+
+`next-i18next` jest prawdopodobnie najpopularniejszą opcją, ponieważ był jednym z pierwszych rozwiązań i18n dla aplikacji JavaScript. Posiada on wiele wtyczek społecznościowych. Ma on te same główne wady co `next-intl`. Pakiet jest szczególnie ciężki (~18 KB dla `I18nProvider` + `useTranslation`, około 3-krotność `next-intlayer`).
+
+Różnią się również formaty komunikatów: `next-intl` używa ICU MessageFormat, podczas gdy `i18next` używa własnego formatu.
+
+**(Next International)** (`next-international@1.3.1`):
+
+`next-international` również radzi sobie z powyższymi problemami, ale nie różni się zbytnio od `next-intl` czy `next-i18next`. Zawiera on funkcję `scopedT()` dla tłumaczeń specyficznych dla przestrzeni nazw, ale jej użycie nie ma praktycznie żadnego wpływu na rozmiar pakietu.
+
+**(Lingui)** (`@lingui/core@5.3.0`):
+
+`Lingui` jest często chwalony. Osobiście uznałem, że proces `lingui extract` / `lingui compile` jest bardziej złożony niż w przypadku alternatyw, bez wyraźnej przewagi. Zauważyłem również niespójne składnie, które mylą AI (np. `t()`, `t''`, `i18n.t()`, `<Trans>`).
+
+### 4 — Rekomendacje
+
+**(Next Translate)** (`next-translate@3.1.2`):
+
+`next-translate` to moja główna rekomendacja, jeśli lubisz API w stylu `t()`. Działa on elegancko poprzez `next-translate-plugin`, ładując przestrzenie nazw przez `getStaticProps` za pomocą loadera Webpack / Turbopack. Jest to również najlżejsza opcja w tym zestawieniu (~2.5 KB). Jeśli chodzi o przestrzenie nazw, definiowanie ich na poziomie strony lub trasy w konfiguracji jest przemyślane i łatwiejsze w utrzymaniu niż w przypadku głównych alternatyw, takich jak **next-intl** czy **next-i18next**. W wersji `3.1.2` zauważyłem, że statyczne renderowanie nie działało; Next.js powracał do renderowania dynamicznego.
+
+**(Intlayer)** (`next-intlayer@8.7.5`):
+
+Nie będę osobiście oceniał `next-intlayer` ze względu na obiektywizm, ponieważ jest to moje własne rozwiązanie.
+
+### Notatka osobista
+
+Ta notatka jest osobista i nie wpływa na wyniki benchmarku. W świecie i18n często widać konsensus wokół wzorca `const t = useTranslation('xx')` + `<>{t('xx.xx')}</>`.
+
+W aplikacjach React wstrzykiwanie funkcji jako `ReactNode` jest w mojej ocenie anty-wzorcem. Dodaje to również zbędną złożoność i narzut wykonania JavaScript (nawet jeśli prawie niezauważalny).

package/docs/pl/benchmark/tanstack.md

@@ -0,0 +1,193 @@
+---
+createdAt: 2026-04-20
+updatedAt: 2026-04-21
+title: Najlepsze rozwiązanie i18n dla TanStack Start w 2026 r. - Raport Benchmark
+description: Porównaj biblioteki internacjonalizacji dla TanStack Start, takie jak react-i18next, use-intl i Intlayer. Szczegółowy raport wydajności dotyczący rozmiaru pakietu, wycieków i reaktywności.
+keywords:
+  - benchmark
+  - i18n
+  - intl
+  - tanstack
+  - wydajność
+  - intlayer
+slugs:
+  - doc
+  - benchmark
+  - tanstack
+author: Aymeric PINEAU
+applicationTemplate: https://github.com/intlayer-org/benchmark-i18n-tanstack-start-template
+history:
+  - version: 8.7.5
+    date: 2026-01-06
+    changes: "Inicjalizacja benchmarka"
+---
+
+# Biblioteki i18n dla TanStack Start — Raport Benchmark 2026
+
+Ta strona to raport z benchmarku rozwiązań i18n w TanStack Start.
+
+## Spis Treści
+
+<Toc/>
+
+## Interaktywny Benchmark
+
+<I18nBenchmark framework="tanstack" vertical/>
+
+## Referencja wyników:
+
+<iframe 
+  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;">
+</iframe>
+
+> https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-tanstack.md
+
+Zobacz pełne repozytorium benchmarka [tutaj](https://github.com/intlayer-org/benchmark-i18n/tree/main).
+
+## Wprowadzenie
+
+Rozwiązania internaucjonalizacji należą do najcięższych zależności w aplikacji React. W TanStack Start głównym ryzykiem jest przesyłanie niepotrzebnych treści: tłumaczeń dla innych stron i innych lokalizacji w pakiecie pojedynczej trasy.
+
+W miarę rozwoju aplikacji problem ten może szybko spowodować gwałtowny wzrost ilości kodu JavaScript wysyłanego do klienta i spowolnić nawigację.
+
+W praktyce, w przypadku najmniej zoptymalizowanych implementacji, strona zinternacjonalizowana może okazać się kilka razy cięższa niż wersja bez i18n.
+
+Inny wpływ dotyczy doświadczenia programisty (DX): sposobu deklarowania treści, typów, organizacji przestrzeni nazw, ładowania dynamicznego i reaktywności przy zmianie lokalizacji.
+
+## Przetestuj swoją aplikację
+
+Aby szybko wykryć problemy z wyciekami i18n, przygotowałem darmowy skaner dostępny [tutaj](https://intlayer.org/i18n-seo-scanner).
+
+<iframe src="https://intlayer.org/i18n-seo-scanner" width="100%" height="600px" style="border:none;"/>
+
+## Problem
+
+Dwie dźwignie są niezbędne do ograniczenia kosztów wielojęzycznej aplikacji:
+
+- Podział treści na strony / przestrzenie nazw, aby nie ładować całych słowników, gdy nie są one potrzebne.
+- Dynamiczne ładowanie odpowiedniej lokalizacji tylko wtedy, gdy jest to potrzebne.
+
+Zrozumienie technicznych ograniczeń tych podejść:
+
+**Ładowanie dynamiczne**
+
+Bez dynamicznego ładowania większość rozwiązań przechowuje komunikaty w pamięci od pierwszego renderowania, co dodaje znaczny narzut w przypadku aplikacji z wieloma trasami i lokalizacjami.
+
+Wraz z ładowaniem dynamicznym akceptujesz kompromis: mniej początkowego kodu JS, ale czasami dodatkowe żądanie przy zmianie języka.
+
+**Podział treści (Content splitting)**
+
+Składnie oparte na `const t = useTranslation()` + `t('a.b.c')` są bardzo wygodne, ale często zachęcają do utrzymywania dużych obiektów JSON w czasie wykonywania. Ten model utrudnia usuwanie kodu (tree-shaking), chyba że biblioteka oferuje realną strategię podziału na strony.
+
+## Metodologia
+
+W tym benchmarku porównaliśmy następujące biblioteki:
+
+- `Base App` (Brak biblioteki i18n)
+- `react-intlayer` (v8.7.5-canary.0)
+- `react-i18next` (v17.0.2)
+- `use-intl` (v4.9.1)
+- `@lingui/core` (v5.3.0)
+- `@inlang/paraglide-js` (v2.15.1)
+- `tolgee` (v7.0.0)
+- `react-intl` (v10.1.1)
+- `wuchale` (v0.22.11)
+- `gt-react` (vlatest)
+- `lingo.dev` (v0.133.9)
+
+Frameworkiem jest `TanStack Start` z wielojęzyczną aplikacją składającą się z **10 stron** i **10 języków**.
+
+Porównaliśmy **cztery strategie ładowania**:
+
+| Strategia                | Brak przestrzeni nazw (globalna)                  | Z przestrzeniami nazw (scoped)                                                   |
+| :----------------------- | :------------------------------------------------ | :------------------------------------------------------------------------------- |
+| **Ładowanie statyczne**  | **Static**: Wszystko w pamięci przy starcie.      | **Scoped static**: Podział na przestrzenie nazw; wszystko ładowane przy starcie. |
+| **Ładowanie dynamiczne** | **Dynamic**: Ładowanie na żądanie na lokalizację. | **Scoped dynamic**: Szczegółowe ładowanie na przestrzeń nazw i lokalizację.      |
+
+## Podsumowanie strategii
+
+- **Static**: Prosta; brak opóźnień sieciowych po początkowym załadowaniu. Minus: duży rozmiar pakietu.
+- **Dynamic**: Redukuje początkową wagę (lazy-loading). Idealna w przypadku wielu lokalizacji.
+- **Scoped static**: Utrzymuje porządek w kodzie (separacja logiczna) bez skomplikowanych dodatkowych żądań sieciowych.
+- **Scoped dynamic**: Najlepsze podejście pod kątem dzielenia kodu (code splitting) i wydajności. Minimalizuje zużycie pamięci, ładując tylko to, czego potrzebuje bieżący widok i aktywna lokalizacja.
+
+## Szczegóły wyników
+
+### 1 — Rozwiązania, których należy unikać
+
+Należy wyraźnie unikać niektórych rozwiązań, takich jak `gt-react` czy `lingo.dev`. Łączą one uzależnienie od dostawcy z zaśmiecaniem bazy kodu. Co gorsza: mimo wielu godzin spędzonych na próbach ich wdrożenia, nigdy nie udało mi się sprawić, by działały poprawnie w TanStack Start (podobnie jak w przypadku `gt-next` w Next.js).
+
+Napotkane problemy:
+
+**(General Translation)** (`gt-react@latest`):
+
+- W przypadku aplikacji o rozmiarze około 110 KB, `gt-react` może dodać ponad 440 KB ekstra (rząd wielkości zaobserwowany w implementacji Next.js w tym samym benchmarku).
+- Komunikat `Quota Exceeded, please upgrade your plan` przy pierwszej próbie budowania z General Translation.
+- Tłumaczenia nie są renderowane; otrzymuję błąd `Error: <T> used on the client-side outside of <GTProvider>`, co wydaje się być błędem w bibliotece.
+- Podczas wdrażania **gt-tanstack-start-react** napotkałem również [problem](https://github.com/generaltranslation/gt/issues/1210#event-24510646961) z biblioteką: błąd `does not provide an export named 'printAST' - @formatjs/icu-messageformat-parser`, który powodował awarię aplikacji. Po zgłoszeniu opiekun naprawił go w ciągu 24 godzin.
+- Biblioteki te stosują anty-wzorzec poprzez funkcję `initializeGT()`, blokując możliwość czystego usuwania kodu z pakietu (tree-shaking).
+
+**(Lingo.dev)** (`lingo.dev@0.133.9`):
+
+- Przekroczenie limitu AI (lub blokująca zależność serwerowa), co sprawia, że budowanie / produkcja są ryzykowne bez płacenia.
+- Kompilator pomijał niemal 40% przetłumaczonej treści. Musiałem przepisać wszystkie struktury `.map` na płaskie bloki komponentów, aby go uruchomić.
+- Ich CLI jest zabugowane i miało tendencję do resetowania pliku konfiguracyjnego bez powodu.
+- Podczas budowania całkowicie wymazywało wygenerowane pliki JSON, gdy dodawana była nowa treść. W rezultacie kilka kluczy mogło wymazać setki istniejących kluczy.
+- Napotkałem problemy z reaktywnością biblioteki w TanStack Start: przy zmianie lokalizacji musiałem wymusić ponowne renderowanie dostawcy, aby działała.
+
+### 2 — Rozwiązania eksperymentalne
+
+**(Wuchale)** (`wuchale@0.22.11`):
+
+Idea stojąca za `Wuchale` jest interesująca, ale nie jest to jeszcze opłacalne rozwiązanie. Napotkałem problemy z reaktywnością tej biblioteki i musiałem wymusić ponowne renderowanie dostawcy, aby aplikacja działała w TanStack Start. Dokumentacja jest również dość niejasna, co utrudnia wdrożenie.
+
+### 3 — Akceptowalne rozwiązania
+
+**(Paraglide)** (`@inlang/paraglide-js@2.15.1`):
+
+`Paraglide` oferuje innowacyjne i przemyślane podejście. Mimo to w tym benchmarku reklamowany przez firmę tree-shaking nie zadziałał w mojej implementacji Next.js ani w TanStack Start. Przepływ pracy i DX są również bardziej złożone niż w przypadku innych opcji. Osobiście nie jestem fanem konieczności regenerowania plików JS przed każdym przesłaniem kodu (push), co stwarza ciągłe ryzyko konfliktów scalania dla programistów przy Pull Requestach.
+
+**(Tolgee)** (`tolgee@7.0.0`):
+
+`Tolgee` rozwiązuje wiele z wymienionych wcześniej problemów. Uznałem jednak, że trudniej z nim zacząć niż z innymi narzędziami o podobnym podejściu. Nie zapewnia on bezpieczeństwa typów, co sprawia, że bardzo trudno jest wyłapać brakujące klucze w czasie kompilacji. Musiałem opakować API Tolgee we własne API, aby dodać wykrywanie brakujących kluczy.
+
+W TanStack Start miałem również problemy z reaktywnością: przy zmianie lokalizacji musiałem wymusić ponowne renderowanie dostawcy i zasubskrybować zdarzenia zmiany lokalizacji, aby ładowanie w innym języku zachowywało się poprawnie.
+
+**(use-intl)** (`use-intl@4.9.1`):
+
+`use-intl` jest obecnie najmodniejszym elementem „intl” w ekosystemie React (z tej samej rodziny co `next-intl`) i jest często forsowany przez agentów AI, ale moim zdaniem niesłusznie w środowisku, w którym liczy się wydajność. Rozpoczęcie pracy jest dość proste. W praktyce proces optymalizacji i ograniczania wycieków jest dość złożony. Podobnie połączenie dynamicznego ładowania + przestrzeni nazw + typów TypeScript bardzo spowalnia rozwój.
+
+W TanStack Start unikasz pułapek specyficznych dla Next.js (`setRequestLocale`, statyczne renderowanie), ale główny problem pozostaje ten sam: bez ścisłej dyscypliny pakiet szybko przenosi zbyt wiele komunikatów, a utrzymanie przestrzeni nazw dla każdej trasy staje się uciążliwe.
+
+**(react-i18next)** (`react-i18next@17.0.2`):
+
+`react-i18next` jest prawdopodobnie najpopularniejszą opcją, ponieważ był jedną z pierwszych, która zaspokoiła potrzeby i18n w aplikacjach JavaScript. Posiada on również szeroki zestaw wtyczek społecznościowych dla konkretnych problemów.
+
+Mimo to ma on te same główne wady co stosy zbudowane na `t('a.b.c')`: optymalizacje są możliwe, ale bardzo czasochłonne, a duże projekty niosą ze sobą ryzyko wpadnięcia w złe praktyki (przestrzenie nazw + ładowanie dynamiczne + typy).
+
+Różnią się również formaty komunikatów: `use-intl` używa ICU MessageFormat, podczas gdy `i18next` używa własnego formatu — co komplikuje narzędzia lub migracje, jeśli się je miesza.
+
+**(Lingui)** (`@lingui/core@5.3.0`):
+
+`Lingui` jest często chwalony. Osobiście uznałem, że proces pracy wokół `lingui extract` / `lingui compile` jest bardziej złożony niż w przypadku innych podejść, bez wyraźnej przewagi w tym benchmarku TanStack Start. Zauważyłem również niespójne składnie, które mylą AI (np. `t()`, `t''`, `i18n.t()`, `<Trans>`).
+
+**(react-intl)** (`react-intl@10.1.1`):
+
+`react-intl` to wydajna implementacja zespołu Format.js. DX pozostaje rozwlekły: `const intl = useIntl()` + `intl.formatMessage({ id: "xx.xx" })` dodaje złożoność, dodatkową pracę JavaScript i wiąże globalną instancję i18n z wieloma węzłami w drzewie React.
+
+### 4 — Rekomendacje
+
+Ten benchmark TanStack Start nie ma bezpośredniego odpowiednika `next-translate` (wtyczka Next.js + `getStaticProps`). Dla zespołów, które naprawdę chcą API `t()` z dojrzałym ekosystemem, `react-i18next` i `use-intl` pozostają „rozsądnymi” wyborami, ale przygotuj się na zainwestowanie dużej ilości czasu w optymalizację, aby uniknąć wycieków.
+
+**(Intlayer)** (`react-intlayer@8.7.5-canary.0`):
+
+Nie będę osobiście oceniał `react-intlayer` ze względu na obiektywizm, ponieważ jest to moje własne rozwiązanie.
+
+### Notatka osobista
+
+Ta notatka jest osobista i nie wpływa na wyniki benchmarku. Mimo to w świecie i18n często widać konsensus wokół wzorca takiego jak `const t = useTranslation('xx')` + `<>{t('xx.xx')}</>` dla treści tłumaczonych.
+
+W aplikacjach React wstrzykiwanie funkcji jako `ReactNode` jest w mojej ocenie anty-wzorcem. Dodaje to również zbędną złożoność i narzut wykonania JavaScript (nawet jeśli prawie niezauważalny).

package/docs/pt/benchmark/index.md

@@ -0,0 +1,29 @@
+---
+createdAt: 2026-04-20
+updatedAt: 2026-04-20
+title: Benchmark das bibliotecas de i18n
+description: Saiba como o Intlayer se compara a outras bibliotecas de i18n em termos de desempenho e tamanho do bundle.
+keywords:
+  - benchmark
+  - i18n
+  - intl
+  - nextjs
+  - tanstack
+  - intlayer
+slugs:
+  - doc
+  - benchmark
+history:
+  - version: 8.7.5
+    date: 2026-01-06
+    changes: "Início do benchmark"
+---
+
+# Benchmark - Relatório
+
+O Benchmark Bloom é uma suíte de benchmarks de desempenho que mede o impacto real das bibliotecas de i18n (internacionalização) em vários frameworks React e estratégias de carregamento.
+
+Abaixo estão os relatórios detalhados e a documentação técnica de cada framework:
+
+- [**Relatório de benchmark do Next.js**](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/benchmark/nextjs.md)
+- [**Relatório de benchmark do TanStack Start**](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/benchmark/tanstack.md)