@intlayer/docs 9.0.0-canary.3 → 9.0.0-canary.5

package/docs/pl/autoFill.md

@@ -35,6 +35,26 @@ author: aymericzip
 
 **Pliki deklaracji autouzupełniania** w Twoim CI to sposób na przyspieszenie procesu tworzenia oprogramowania.
 
+## Zrozumienie zachowania
+
+Polecenie `fill` zawiera dwa tryby:
+
+- **Complete**: Automatycznie wypełnia całą brakującą treść dla każdej lokalizacji i edytuje bieżący plik lub inny plik, jeśli jest określony. To znaczy, tryb complete pominiesz tłumaczenie istniejącej treści, jeśli jest już przetłumaczona.
+- **Review**: Automatycznie wypełnia **całą** treść dla każdej lokalizacji i generuje dla określonego pliku lub innego pliku, jeśli jest określony.
+
+Polecenie fill będzie przetwarzać wszystkie pliki deklaracji treści lokalizacji. To znaczy, nie będzie przetwarzać zdalnej treści z CMS. CMS zawiera własne zarządzanie tłumaczeniami.
+Jeśli używasz wtyczek takich jak `@intlayer/sync-json-plugin`, Intlayer przekształci pliki JSON w pliki deklaracji treści lokalizacji. To znaczy, będą przetwarzane przez polecenie `fill`.
+
+Nowo wygenerowane pliki zawierają instrukcję `filled` jako metadane słownika. Instrukcja ta będzie używana przez Intlayer do określenia, czy plik został automatycznie wypełniony, czy nie, i pominie ten plik z ponownego tłumaczenia, jeśli jest obecny.
+
+Intlayer będzie również uwzględniać następującą instrukcję do automatycznego wypełniania:
+
+- Z twojego pliku `.content.{ts|js|json}` → instrukcja `fill`
+- Z pliku konfiguracyjnego `.intlayer.config.ts` → instrukcja `dictionary.fill`
+- Będzie domyślnie ustawiona na `true` w przeciwnym razie
+
+W przypadku plików deklaracji treści dla poszczególnych lokalizacji instrukcja `true` zostanie zastąpiona przez `./{{fileName}}.fill.content.json`. Dzieje się tak, ponieważ plik deklaracji treści dla poszczególnych lokalizacji nie może otrzymać dodatkowej zlokalizowanej treści. Dlatego wygeneruje nowy plik, aby nie nadpisać istniejącego pliku.
+
 ## Domyślne zachowanie
 
 Domyślnie `fill` jest ustawione globalnie na `true`, co oznacza, że Intlayer automatycznie wypełni wszystkie pliki zawartości i edytuje sam plik. To zachowanie można dostosować na kilka sposobów:

package/docs/pl/benchmark/___NOTE.md

@@ -0,0 +1,101 @@
+---
+createdAt: 2024-03-07
+updatedAt: 2024-03-07
+title: Notatki z benchmarku
+description: Szczegółowe notatki i obserwacje z benchmarku frameworka i18n.
+keywords:
+  - benchmark
+  - i18n
+  - notatki
+  - porównanie
+slugs:
+  - doc
+  - benchmark
+  - note
+author:
+  name: Aymeric PINEAU
+  github: aymericzip
+---
+
+**gt-react** / **gt-next**
+
+Nie byłem w stanie przetestować gt-react / gt-next. Biblioteki nie są funkcjonalne i łamią aplikację.
+
+- Nie byłem w stanie przetestować reaktywności aplikacji.
+- 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 implementacji **gt-tanstack-start-react**, natknąłem się na problem z biblioteką: `does not provide an export named 'printAST' - @formatjs/icu-messageformat-parser`, co powodowało, że aplikacja się łamała. Po zgłoszeniu tego problemu, opiekun naprawił go w ciągu 24 godzin.
+- Ta biblioteka wymaga zależności od serwera General Translation do tłumaczenia. Nawet jedna próba tłumaczenia zwróciła błąd: `Quota Exceeded, please upgrade your plan`. Ryzyko blokady dostawcy jest wysokie.
+- Te biblioteki używają antywzorca poprzez funkcję `initializeGT()`, które blokują bundle od czystego tree-shakingu.
+- Dla implementacji nextjs, biblioteka blokuje statyczne renderowanie stron Next.js.
+
+**Lingo.dev**
+
+- Ciężka zależność od serwera lingo.dev do generowania tłumaczeń. Nawet jeśli zawierają bardziej hojny bezpłatny poziom niż General Translation, ryzyko blokady dostawcy jest wysokie.
+- Konfiguracja nie była prosta. Musiałem reverse-inżynierować ich kod i wymuszać przesłanie zmiennej środowiskowej, aby to zadziałało.
+- Ich CLI jest bugowy i zwykł przepisywać plik konfiguracyjny za każdym razem, gdy go używałem.
+- Kompilator brakował prawie 40% przetłumaczonej zawartości. Musiałem przepisać wszystkie `.map` na płaskie bloki komponentów, aby to zadziałało.
+- Spotkałem się z problemami reaktywności z biblioteką. Przy zmianie lokali musiałem wymusić ponowne renderowanie dostawcy, aby to zadziałało.
+- Przy przebudowie czasami losowo usuwało wszystkie wygenerowane tłumaczenia bez żadnego powodu.
+
+**next-translate**
+
+- Dla aplikacji Next.js, ta biblioteka była wielkim odkryciem; podejście jest niezwykle dobrze przemyślane i łatwe do wdrożenia, a wyniki są imponujące. Zysk w porównaniu do innych bibliotek używających składni `t()` jest znaczący, takiej jak **next-intl** lub **next-i18next**.
+- Ta biblioteka używa podejścia transformacji czasu budowania z `react-translate-plugin`: przepisuje strony i wstawia pobieranie zawartości za pomocą `getStaticProps` lub `getServerSideProps` poprzez loader Webpack / Turbopack. Rezultatem jest to, że nigdy nie pobierasz zawartości z innych lokali.
+- Dla namespacing, wybieranie namespaces na poziomie konfiguracji jest również dobrze przemyślane: możesz definiować namespaces dla każdej strony lub trasy. Czyni to utrzymanie znacznie łatwiejszym niż główne alternatywy, takie jak **next-intl** lub **next-i18next**.
+- Ta biblioteka obsługuje zarówno Webpack jak i Turbopack, komponenty klienckie i serwerowe, oraz Pages i App Router.
+- Nawet jeśli to rozwiązanie ma >6 lat, biblioteka jest nadal aktywnie utrzymywana.
+- Nie ma strony internetowej i dokumentacji online; są dostępne tylko na GitHub. Lubię odkrywać świetne biblioteki i naprawiać problemy w czystym podejściu, bez dodatkowych warstw marketingu.
+- Wszystkie stałe są transformowane w funkcje, co prowadzi do antywzorca. Składnia taka jak `const t = useTranslation('xx')` + `<>{t('xx.xx')}</>` wprowadza niepotrzebną złożoność i prowadzi do overhead wykonywania JavaScript.
+- Biblioteka blokuje statyczne renderowanie stron Next.js.
+
+**Tolgee**
+
+- Implementacja była trudna do uzyskania, szczególnie ponieważ biblioteka nie zapewnia bezpieczeństwa typów. Aby wykryć błędne klucze, musiałem ręcznie przepisać logikę bezpieczeństwa typów i ponownie użyć własnej implementacji funkcji `getTranslation`.
+- Ta biblioteka obsługuje zarówno Webpack jak i Turbopack, komponenty klienckie i serwerowe, oraz Pages i App Router.
+- Nie ma strony internetowej i dokumentacji online; są dostępne tylko na GitHub.
+- Na tanstack start spotkałem się również z problemami reaktywności z biblioteką. Przy zmianie lokali musiałem wymusić ponowne renderowanie dostawcy. Musiałem zasubskrybować zdarzenie zmiany lokali, aby to zadziałało podczas ładowania strony w innej lokali.
+- Dla implementacji nextjs, biblioteka blokuje statyczne renderowanie stron Next.js.
+- Spotkałem się również z problemami z DevTools dostarczonym przez bibliotekę. Zwykł rejestrować błędy w konsoli po stronie serwera.
+
+**next-translate**
+
+- Nawet jeśli to rozwiązanie ma >6 lat, biblioteka jest nadal aktywnie utrzymywana.
+- Ta biblioteka używa podejścia transformacji czasu budowania z `react-translate-plugin`: przepisuje strony i wstawia pobieranie zawartości za pomocą `getStaticProps` lub `getServerSideProps`. Rezultatem jest to, że nigdy nie pobierasz zawartości z innych lokali.
+
+**next-intl** / **use-intl** / **next-i18next** / **react-i18next** / **next-international**
+
+- Takie same zalety i wady dla wszystkich tych bibliotek, które używają składni `t()`.
+- Optymalizacje są możliwe, ale niezwykle czasochłonne. Dobre praktyki nie są wyraźnie wyróżnione, i może być łatwe dla agentów lub juniorskich deweloperów, aby zaszkodzić wydajności aplikacji przez złe praktyki. Szczególnie przy użyciu namespacing plus dynamiczne ładowanie, zachowanie bezpieczeństwa typów i wiedza dokładnie, który namespace powinien być uwzględniony na której stronie jest koszmarem.
+- Wszystkie te biblioteki oferują podobne podejście, dobrze połączone z systemem reaktywności React. Ale `next-intl` oferuje dodatkowe funkcje, takie jak obsługa middleware, formatery, itp.
+- Formaty wiadomości różnią się między bibliotekami. `next-intl` używa formatu ICU MessageFormat, podczas gdy `i18next` używa własnego formatu.
+- **next-intl** jest znacznie lżejszym rozwiązaniem niż **i18next**, ale pozostaje ciężkie i słabo zoptymalizowane.
+- **next-intl** zwykł blokować statyczne renderowanie stron Next.js. Zapewnia funkcję naprawy o nazwie `setRequestLocale()`, która nie była łatwa do zrozumienia przyczyny problemu lub jak go naprawić. Ten problem wydaje się został rozwiązany i nie blokuje już statycznego renderowania dla scentralizowanej zawartości, takiej jak `en.json` / `fr.json` / `es.json` / itp. Należy pamiętać, że nadal blokuje statyczne renderowanie, gdy zawartość jest ograniczona do namespaces, takich jak `en/shared.json` / `fr/shared.json` / `es/shared.json` / itp.
+- Oba rozwiązania nie oferują sposobu na tłumaczenie synchronicznych komponentów serwerowych, takich jak navbar design-system, stopka, itp. W rezultacie wszystkie komponenty muszą być tłumaczone po stronie klienta.
+- Wszystkie stałe są transformowane w funkcje, co prowadzi do antywzorca. Składnia taka jak `const t = useTranslation('xx')` + `<>{t('xx.xx')}</>` wprowadza niepotrzebną złożoność i prowadzi do overhead wykonywania JavaScript.
+- **next-international** zawiera funkcję `scopedT()`, która pozwala na tłumaczenie zawartości w określonym namespace, co utrudnia proces refaktoringu do celów optymalizacji. Ale ponieważ nie ma sposobu na podział json w namespaces, ta funkcja jest raczej bezużyteczna. Poprawia tylko DX, ale nie ma wpływu na rozmiar bundle.
+
+**Lingui**
+
+- Rozsądna wydajność i wpływ, z dobrym poszanowaniem najlepszych praktyk.
+- Implementacja jest złożona dla funkcji, które nie są komponentami strony, takimi jak Next.js `generateMetadata`. Musisz stworzyć nową instancję i18n, wybrać wiadomości do załadowania, a następnie je przetłumaczyć.
+- Przepływ może być nieco złożony do zrozumienia przy pierwszej implementacji.
+- Myląca składnia, np. `t()`, `t''`, `i18n.t()`, `<Trans>`. Wiedza, które praktyki należy używać w aplikacji, nie jest intuicyjna.
+
+**Wuchale**
+
+- Świetne podejście próbujące automatyzować proces ekstrakcji i tłumaczenia bez jakiejkolwiek składni `t()`.
+- Rozwiązanie Svelte-first. Adaptacja React biblioteki nie jest tak dojrzała jak wersja Svelte. Reaktywność aplikacji React nie zadziałała. Musiałem wymusić ponowne renderowanie dostawcy przy zmianie lokali, używając niestandardowego stanu `isMounted()/effect` aby to zadziałało.
+- Używa antywzorca dla funkcji inicjalizacji, aby załadować się przed inicjalizacją routera.
+
+**Paraglide**
+
+- Teoretycznie dla aplikacji zawierających wiele lokali, Paraglide zawiera wszystkie wiadomości w bundle. Nie ma sposobu na dynamiczne ładowanie wiadomości. Nawet jeśli promują optymalizacja `tree-shaking`, biblioteka głównie przenosi problem bundlowania gdzie indziej. Przyszła poprawa dla dynamicznego ładowania wydaje się niemożliwa biorąc pod uwagę architekturę biblioteki. Użycie dynamicznego ładowania prowadziłoby do tysięcy żądań do serwera.
+- W praktyce, wynik używania Paraglide jest jeszcze gorszy niż oczekiwany. Na nextjs (Turbopack) jak dla tanstack start (Rolldown), bundler nawet nie tree shake wiadomości. W rezultacie, ostateczny rozmiar bundle zawiera zawartość ze wszystkich stron i wszystkich lokali.
+- Złożony przepływ używający plików deklaracji JSON jako źródła prawdy, plus generacja plików wiadomości w czasie budowania, następnie ręczne importy w każdym komponencie.
+- Wszystkie stałe są transformowane w funkcje, co prowadzi do antywzorca. Składnia taka jak `import * as m from '@/messages'` + `<>{m.myContent()}</>` wprowadza niepotrzebną złożoność i prowadzi do overhead wykonywania JavaScript.
+- W porównaniu z innymi rozwiązaniami, które używają react context do efektywnego pobierania aktualnej lokali do renderowania zawartości, Paraglide będzie czytać dla każdego węzła zawartości zaimportowanej lokalę z localeStorage / cookie itp. Prowadzi to do wykonywania niepotrzebnej logiki.
+
+**react-intl**
+
+- Wydajna implementacja, zrobiona przez zespół Format.js.
+- Myląca DX przy użyciu `const intl = useIntl()` + `intl.formatMessage({ id: "xx.xx" })` wprowadza niepotrzebną złożoność, prowadzi do overhead wykonywania JavaScript i łączy globalną instancję i18n ze wszystkimi węzłami komponentów.

package/docs/pl/benchmark/___nextjs.md

@@ -0,0 +1,198 @@
+---
+createdAt: 2026-04-20
+updatedAt: 2026-04-21
+title: Najlepsze rozwiązanie i18n dla Next.js w 2026 - Raport benchmarku
+description: Porównaj biblioteki internacjonalizacji Next.js takie jak next-intl, next-i18next i Intlayer. Szczegółowy raport wydajności dotyczący rozmiaru bundle, wycieków i reaktywności.
+keywords:
+  - benchmark
+  - i18n
+  - intl
+  - nextjs
+  - wydajność
+  - intlayer
+slugs:
+  - doc
+  - benchmark
+  - nextjs
+author:
+  name: Aymeric PINEAU
+  github: aymericzip
+history:
+  - version: 8.7.5
+    date: 2026-01-06
+    changes: "Init benchmark"
+---
+
+# Raport benchmarku bibliotek i18n dla Next.js w 2026
+
+Ta strona jest raportem benchmarku dla rozwiązań i18n dla Next.js.
+
+## Spis treści
+
+<Toc/>
+
+## Interaktywny benchmark
+
+<I18nBenchmark framework="nextjs" vertical/>
+
+## Referencja wyników:
+
+<ClickToOpenIframe
+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;"
+/>
+
+> [Patrz kompletne dane benchmarku](https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-nextjs.md)
+
+## Wstęp
+
+Rozwiązania internacjonalizacyjne są bibliotekami o dużym wpływie na aplikację. Głównym ryzykiem jest załadowanie zawartości wszystkich stron i wszystkich języków dla pojedynczej przeglądanej strony.
+
+Wraz z rozwojem aplikacji rozmiar bundle ewoluuje wykładniczo, co może znacząco spowolnić wydajność aplikacji.
+
+Jako przykład, dla najgorszych uczniów, po internacjonalizacji strona może skończyć się prawie 4 razy bardziej objętościowa.
+
+Innym wpływem rozwiązań internacjonalizacyjnych jest spowolnienie rozwoju. Transformowanie komponentów i organizowanie zawartości we wszystkich językach jest czasochłonne.
+
+Problem jest złożony, wiele rozwiązań pojawiło się aby rozwiązać problem i18n. Niektóre rozwiązania skupiają się na DX, inne na wydajności, inne na skalowalności, itp.
+
+Intlayer jest rozwiązaniem próbującym optymalizować wszystkie te aspekty.
+
+## Testuj swoją aplikację
+
+Aby wykryć te problemy, mam skonfigurowany bezpłatny skaner, który możesz przetestować [tutaj](https://intlayer.org/i18n-seo-scanner).
+
+## Problematyka
+
+Istnieją dwa główne aspekty aby ograniczyć wpływ wielojęzycznej aplikacji na bundle aplikacji:
+
+- Podziel swoje JSON (lub zawartość) na wiele plików / zmiennych / namespaces aby umożliwić bundlerowi tree-shake zawartość nieużywaną na stronie
+- Dynamicznie załaduj zawartość strony tylko w języku strony
+
+Zrozumienie ograniczeń technicznych dla tych podejść:
+
+**Dynamiczne ładowanie**
+
+Nawet jeśli deklarujesz swoje trasy jako `[locale]/page.tsx`, czy to z Webpack czy Turbopack, i mimo że `getStaticParams` jest zdefiniowany, bundler nie traktuje `locale` jako zmiennej statycznej. To oznacza, że bundler załaduje zawartość wszystkich języków dla każdej strony. Jedyną opcją aby ograniczyć ten problem jest załadowanie zawartości poprzez dynamiczny import (np. `import('./locales/${locale}.json')`).
+
+To co się dzieje podczas budowania, to że Next.js generuje plik JS (bundle) dla każdego języka (np. `./locales_fr_12345.js`). Następnie po wysłaniu witryny do klienta, gdy strona jest wykonywana, to przeglądarka zmieni się w wykonanie dodatkowego żądania HTTP, żądając wymaganego pliku JS (np. `./locales_fr_12345.js`).
+
+> Innym sposobem na odpowiedź na ten sam problem jest użycie metody `fetch()` aby dynamicznie żądać pliku JSON. To jest przypadek `Tolgee` poprzez umieszczenie JSON w folderze `/public` lub `next-translate`, które opierają się na funkcji `getStaticProps` aby załadować zawartość. Ale przepływ pozostaje taki sam, przeglądarka wykona dodatkowe żądanie HTTP aby załadować asset.
+
+**Podział zawartości**
+
+Jeśli używasz składni takiej jak `const t = useTranslation()` + `t('my-object.my-sub-object.my-key')`, JSON musi być w całości załadowany do bundle, aby następnie być parsowany przez bibliotekę aby wydedukować wartość klucza. Ale to oznacza, że duża część zawartości będzie załadowana w bundle, choć nieużywana na stronie.
+
+Aby odpowiedzieć na ten problem, niektóre biblioteki sugerują deklarowanie ręcznie dla każdej strony, które namespaces powinny być załadowane. To jest przypadek `next-i18next`, `next-intl`, `lingui`, `next-translate`, `next-international`.
+
+W porównaniu, `Paraglide` proponuje dodanie dodatkowego kroku, przed budowaniem aby transformować JSON w płaską zmienną, taką jak `const en_my_var = () => 'my value'`. To pozwala (teoretycznie) tree-shake zawartość nieużywaną na stronie. Ale zobaczymy, ta metoda nie jest bez kompromisów.
+
+Na koniec, `Intlayer` proponuje optymalizację w czasie budowania, pozwalającą na zastąpienie użycia `useIntlayer('my-key')` i bezpośrednie dołączenie odpowiadającej zawartości.
+
+## Metodologia
+
+Dla tego benchmarku porównaliśmy następujące biblioteki:
+
+- `Base App` (No i18n library)
+- `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 frameworka `Next.js` w wersji `16.2.4` z trybem `app router`.
+
+Stworzyłem wielojęzyczną aplikację z **10 stronami**, w **10 językach**.
+
+I porównałem **4 strategie ładowania**:
+
+| Strategi              | Bez Namespaces (Global)                        | Z Namespaces (Scoped)                                                |
+| :--------------------- | :------------------------------------------------ | :---------------------------------------------------------------------- |
+| **Ładowanie Static**  | **Static** : Wszystko w pamięci przy uruchomieniu.        | **Scoped Static** : Podzielone na namespace, wszystko załadowane przy uruchomieniu.   |
+| **Ładowanie Dynamic** | **Dynamic** : Ładowanie na żądanie przez lokalę. | **Scoped Dynamic** : Ładowanie granularne przez namespace i lokalę. |
+
+## Streszczenie strategii
+
+- **Static** : Proste, bez opóźnień sieciowych po załadowaniu początkowym. Wadą : wysoki rozmiar bundle.
+- **Dynamic** : Zmniejsza początkowy waga (lazy-loading). Idealne dla dużej liczby lokali.
+- **Scoped Static** : Pozwala na czystą organizację kodu (logiczne separacja) bez dodatkowego kosztu złożonych żądań sieciowych.
+- **Scoped Dynamic** : Optymalne podejście do _Code Splitting_ i wydajności. Minimalizuje obciążenie pamięci ładując tylko niezbędne dla bieżącego widoku i aktywnej lokali.
+
+## Szczegóły wyników
+
+### 1 - Rozwiązania do uniknięcia
+
+Pewne rozwiązania takie jak `gt-next` lub `lingo.dev` są wyraźnie rozwiązaniami do uniknięcia. Te rozwiązania integrują kombo blokady dostawcy + zatrucie bazy kodu. I górą wszystkiego jest to, że pomimo wielu godzin próby ich implementacji, nigdy mi się nie udało je uruchomić. Zarówno dla Tanstack start jak i Next.js.
+
+Lista napotkaných problemów:
+
+**(General Translation)** (`gt-next@6.16.5`):
+
+- Dla aplikacji 110kb, `gt-react` dodaje do niej ponad 440kb dodatkowego.
+- `Quota Exceeded, please upgrade your plan`, od pierwszego budowania z rozwiązaniem 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 implementacji **gt-tanstack-start-react**, natknąłem się na [problem](https://github.com/generaltranslation/gt/issues/1210#event-24510646961) z biblioteką: `does not provide an export named 'printAST' - @formatjs/icu-messageformat-parser`, co powodowało, że aplikacja się łamała. 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`):
+
+- Przywłaszczony limit AI, całkowicie blokujący budowanie. Jest wtedy niemożliwe pushowanie do produkcji bez płacenia.
+- Kompilator brakował prawie 40% przetłumaczonej zawartości. Musiałem przepisać wszystkie `.map` na płaskie bloki komponentów aby to zadziałało.
+- Ich CLI jest bugowy i zwykł resetować plik konfiguracyjny bez powodu.
+- Przy budowaniu, całkowicie wymazywał wygenerowane JSON gdy była dodana nowa zawartość. W wyniku, masz tylko 3 klucze usuwające >300 istniejących kluczy.
+
+### 2 - Rozwiązania eksperymentalne
+
+**(Wuchale)** (`wuchale@0.22.11`):
+
+Ideą `Wuchale` jest interesująca, ale nie jest jeszcze na etapie żywotnego rozwiązania. Napotkałem problemy reaktywności z biblioteką i musiałem wymusić ponowne renderowanie dostawcy aby uruchomić aplikację. Dokumentacja jest również stosunkowo niejasna, utrudniając przyjęcie.
+
+**(Paraglide)** (`@inlang/paraglide-js@2.15.1`):
+
+`Paraglide` jest rozwiązaniem oferującym innowacyjne i dobrze przemyślane podejście. Niemniej jednak, w kontekście mojego benchmarku, widać, że tree-shaking, który sprzedają ich firma, nie działa ani dla mojej implementacji Next.js, ani dla Tanstack start. Przepływ i DX jest również bardziej złożony niż inne rozwiązania. I osobiście nie lubię faktu, że muszę przeregenerować pliki JS przed każdym pushowaniem, tworząc ciągłe ryzyko konfliktów między deweloperami poprzez ich PR. Wreszcie, rozwiązanie wydaje się bardziej skupiać na Vite niż na Next.js.
+
+### 3 - Rozwiązania 'ok'
+
+**(Tolgee)** (`tolgee@7.0.0`):
+
+`Tolgee` jest rozwiązaniem odpowiadającym różnym problemom wspominanym wcześniej. Ale znalazłem przyjęcie rozwiązania bardziej złożonym niż inne rozwiązania proponujące podobne podejścia. Rozwiązanie nie proponuje typesafety. To czyni detektywę brakujących kluczy przy kompilacji znacznie bardziej złożoną. Musiałem owrappować funkcje Tolgee własnymi aby dodać detektywę brakujących kluczy.
+
+**(Next Intl)** (`next-intl@4.9.1`):
+
+`next-intl` jest najmodniejszym rozwiązaniem i również najbardziej wypromowanym przez agentów AI, ale moim zdaniem słusznie. Get-started jest dość prosty. Ale w praktyce, proces optymalizacji aby ograniczyć wyciek jest dość złożony. Similarly, współistnienie dynamicznego ładowania + namespacing + typescript types znacznie spowalnia rozwój. Ponadto biblioteka jest dość ciężka (~13kb dla `NextIntlClientProvider` + `useTranslations` hook, co jest >2x bardziej ciężkie niż `next-intlayer`). **next-intl** zwykł blokować statyczne renderowanie stron Next.js. Zapewnia funkcję naprawy o nazwie `setRequestLocale()`. Ten problem wydaje się został częściowo rozwiązany dla scentralizowanej zawartości takich jak `en.json` / `fr.json` / itp. Ale rozwiązanie nadal blokuje statyczne renderowanie gdy zawartość jest ograniczona do namespaces takimi jak `en/shared.json` / `fr/shared.json` / `es/shared.json` / itp.
+
+**(Next I18next)** (`next-i18next@16.0.5`):
+
+`next-i18next` jest prawdopodobnie najpopularniejszym rozwiązaniem faktem, że to była pierwsza rozwiązanie, które pojawiło się aby odpowiedzieć na potrzeby internacjonalizacji aplikacji Javascript. To rozwiązanie również proponuje szeroki zestaw pluginów społeczności aby odpowiedzieć na pewne problemy. Niemniej jednak, to rozwiązanie pokazuje dokładnie takie same czarne punkty co `next-intl`. Ponadto biblioteka jest szczególnie ciężka (~18kb dla `I18nProvider` + `useTranslation` hook, co jest 3x bardziej ciężkie niż `next-intlayer`).
+Ponadto formaty wiadomości różnią się między bibliotekami. `next-intl` używa formatu ICU MessageFormat, podczas gdy `i18next` używa własnego formatu.
+
+**(Next International)** (`next-international@1.3.1`):
+
+`next-international` jest rozwiązaniem odpowiadającym również różnym problemom wspominanym wcześniej, ale nie proponuje znaczącej różnicy w stosunku do `next-intl` lub nawet `next-i18next`. Rozwiązanie zawiera funkcję `scopedT()`, która pozwala na tłumaczenie zawartości w określonym namespace. Niemniej jednak, użycie tej funkcji nie ma czysto i po prostu żadnego wpływu na rozmiar bundle.
+
+**(Lingui)** (`@lingui/core@5.3.0`):
+
+`Lingui` jest rozwiązaniem dla którego słyszałem wiele dobrego. Ale osobiście znalazłem przepływ bazujący na wykonaniu poleceń `lingui extract` / `lingui compile` bardziej złożonym niż inne podejścia, bez znaczącej przewagi. Zauważyłem również brak harmonii między składniami które noszą AI do zamieszania. (np. `t()`, `t''`, `i18n.t()`, `<Trans>`)
+
+### 4 - Moje rekomendacje
+
+**(Next Translate)** (`next-translate@3.1.2`):
+
+`next-translate` jest tutaj moją główną rekomendacją dla tych, którzy lubią użycie funkcji `t()` do tłumaczenia zawartości. To rozwiązanie oferuje eleganckie podejście poprzez `next-transalte-plugin`, optymalizując ładowanie namespaces poprzez `getStaticProps` poprzez loader Webpack / Turbopack. To również najprostsze rozwiązanie ze wszystkich (~2.5kb tylko). Do namespacing, wybieranie namespaces na poziomie konfiguracji jest również dobrze przemyślane: możesz definiować namespaces dla każdej strony lub trasy. Czyni to utrzymanie znacznie łatwiejszym niż główne alternatywy, takie jako **next-intl** lub **next-i18next**. Niemniej jednak zauważyłem, że w wersji `3.1.2`, budowanie w statycznym renderowaniu nie działa. Next.js fallback wtedy na dynamiczne renderowanie.
+
+**(Intlayer)** (`next-intlayer@8.7.5`):
+
+Na koniec, nie będę osobiście sądził `next-intlayer`, z powodu obiektywności, biorąc pod uwagę, że jest to moje własne rozwiązanie.
+
+### Notatka personalna
+
+Ta notatka jest personalna i nie ma wpływu na wyniki benchmarku. Niemniej jednak, w świecie i18n widzimy wyraźny konsensus, którym jest użycie składni takiej jak `const t = useTranslation('xx')` + `<>{t('xx.xx')}</>` do tłumaczenia zawartości.
+Niemniej jednak, w kontekście aplikacji React, iniekcja funkcji w formie `ReactNode` jest moim zdaniem antywzorem. Ponadto, to wprowadza dodatkową złożoność, którą można uniknąć, i overhead wykonywania JavaScript (chociaż niezauważalny).

package/docs/pl/benchmark/___solid.md

@@ -0,0 +1,36 @@
+---
+createdAt: 2026-04-20
+updatedAt: 2026-04-21
+title: Najlepsze rozwiązanie i18n dla Solid w 2026 - Raport benchmarku
+description: Porównaj biblioteki internacjonalizacji Solid. Szczegółowy raport wydajności dotyczący rozmiaru bundle, wycieków i reaktywności.
+keywords:
+  - benchmark
+  - i18n
+  - intl
+  - solid
+  - wydajność
+  - intlayer
+slugs:
+  - doc
+  - benchmark
+  - solid
+author:
+  name: Aymeric PINEAU
+  github: aymericzip
+history:
+  - version: 8.7.5
+    date: 2026-01-06
+    changes: "Init benchmark"
+---
+
+# Raport benchmarku bibliotek i18n dla Solid w 2026
+
+Ta strona jest raportem benchmarku dla rozwiązań i18n dla Solid.
+
+## Interaktywny benchmark
+
+<I18nBenchmark framework="solid" vertical/>
+
+## Referencja wyników
+
+> [Patrz kompletne dane benchmarku](https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-solid.md)

package/docs/pl/benchmark/___svelte.md

@@ -0,0 +1,36 @@
+---
+createdAt: 2026-04-20
+updatedAt: 2026-04-21
+title: Najlepsze rozwiązanie i18n dla Svelte w 2026 - Raport benchmarku
+description: Porównaj biblioteki internacjonalizacji Svelte. Szczegółowy raport wydajności dotyczący rozmiaru bundle, wycieków i reaktywności.
+keywords:
+  - benchmark
+  - i18n
+  - intl
+  - svelte
+  - wydajność
+  - intlayer
+slugs:
+  - doc
+  - benchmark
+  - svelte
+author:
+  name: Aymeric PINEAU
+  github: aymericzip
+history:
+  - version: 8.7.5
+    date: 2026-01-06
+    changes: "Init benchmark"
+---
+
+# Raport benchmarku bibliotek i18n dla Svelte w 2026
+
+Ta strona jest raportem benchmarku dla rozwiązań i18n dla Svelte.
+
+## Interaktywny benchmark
+
+<I18nBenchmark framework="svelte" vertical/>
+
+## Referencja wyników
+
+> [Patrz kompletne dane benchmarku](https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-svelte.md)

package/docs/pl/benchmark/___tanstack.md

@@ -0,0 +1,36 @@
+---
+createdAt: 2026-04-20
+updatedAt: 2026-04-21
+title: Najlepsze rozwiązanie i18n dla TanStack Start w 2026 - Raport benchmarku
+description: Porównaj biblioteki internacjonalizacji TanStack Start takie jak react-i18next, use-intl i Intlayer. Szczegółowy raport wydajności dotyczący rozmiaru bundle, wycieków i reaktywności.
+keywords:
+  - benchmark
+  - i18n
+  - intl
+  - tanstack
+  - wydajność
+  - intlayer
+slugs:
+  - doc
+  - benchmark
+  - tanstack
+author:
+  name: Aymeric PINEAU
+  github: aymericzip
+history:
+  - version: 8.7.5
+    date: 2026-01-06
+    changes: "Init benchmark"
+---
+
+# Raport benchmarku bibliotek i18n dla TanStack Start w 2026
+
+Ta strona jest raportem benchmarku dla rozwiązań i18n dla TanStack Start.
+
+## Interaktywny benchmark
+
+<I18nBenchmark framework="tanstack" vertical/>
+
+## Referencja wyników
+
+> [Patrz kompletne dane benchmarku](https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-tanstack.md)

package/docs/pl/benchmark/___vue.md

@@ -0,0 +1,36 @@
+---
+createdAt: 2026-04-20
+updatedAt: 2026-04-21
+title: Najlepsze rozwiązanie i18n dla Vue w 2026 - Raport benchmarku
+description: Porównaj biblioteki internacjonalizacji Vue. Szczegółowy raport wydajności dotyczący rozmiaru bundle, wycieków i reaktywności.
+keywords:
+  - benchmark
+  - i18n
+  - intl
+  - vue
+  - wydajność
+  - intlayer
+slugs:
+  - doc
+  - benchmark
+  - vue
+author:
+  name: Aymeric PINEAU
+  github: aymericzip
+history:
+  - version: 8.7.5
+    date: 2026-01-06
+    changes: "Init benchmark"
+---
+
+# Raport benchmarku bibliotek i18n dla Vue w 2026
+
+Ta strona jest raportem benchmarku dla rozwiązań i18n dla Vue.
+
+## Interaktywny benchmark
+
+<I18nBenchmark framework="vue" vertical/>
+
+## Referencja wyników
+
+> [Patrz kompletne dane benchmarku](https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-vue.md)

package/docs/pl/benchmark/solid.md

@@ -118,6 +118,28 @@ Porównaliśmy **cztery strategie ładowania**:
 - **Scoped static**: Utrzymuje porządek w kodzie (logiczna separacja) bez skomplikowanych dodatkowych zapytań sieciowych.
 - **Scoped dynamic**: Najlepsze podejście dla _code splittingu_ 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, a następnie zapisałem, co faktycznie pojawiło się na sieci i jak długo to trwało. Rozmiary są podawane **po normalnej kompresji internetowej**, ponieważ jest to bliższe temu, co ludzie pobierają, niż surowe liczby źródła.
+
+- **Rozmiar biblioteki internacjonalizacji**: Po bundlingu, tree-shakingu i minifikacji, rozmiar biblioteki i18n to rozmiar providerów + kodu hooks/primitives w pustym komponencie. Nie obejmuje ładowania plików tłumaczeń. Odpowiada na pytanie, jak kosztowna jest biblioteka zanim twoja zawartość wejdzie do gry.
+
+- **JavaScript na stronę**: Dla każdej trasy benchmarku, ile skryptu przeglądarka pobiera dla tej wizyty, uśrednione na stronach w zestawie (i na lokalizacjach, gdzie raport je łączy). Ciężkie strony to wolne strony.
+
+- **Wyciek z innych lokalizacji**: To zawartość tej samej strony, ale w innym języku, która byłaby załadowana przez pomyłkę na audytowanej stronie. Ta zawartość jest zbędna i powinna być unikana. (np. zawartość strony `/fr/about` w bundlu strony `/en/about`)
+
+- **Wyciek z innych tras**: Ten sam pomysł dla **innych ekranów** w aplikacji: czy ich kopia jedzie razem, gdy otworzysz tylko jedną stronę. (np. zawartość strony `/en/about` w bundlu strony `/en/contact`). Wysoki wynik sugeruje słabe dzielenie lub zbyt szerokie bundle'i.
+
+- **Średni rozmiar bundle'u komponentu**: Typowe elementy UI są mierzone **jeden po drugim** zamiast ukrywania się wewnątrz jednej gigantycznej liczby aplikacji. Pokazuje, czy internacjonalizacja po cichu rozszerza zwykłe komponenty. Na przykład, jeśli twój komponent zostanie ponownie renderowany, załaduje wszystkie te dane z pamięci. Przywiązanie gigantycznego JSON'a do dowolnego komponentu jest jak podłączenie dużego magazynu nieużywanych danych, który spowolni wydajność twoich komponentów.
+
+- **Responsywność przełącznika języka**: Przełączam język przy użyciu kontrolki aplikacji i mierzę, jak długo trwa, zanim strona wyraźnie się zmieni, co odwiedzający zauważy, a nie laboratoryjny mikrokrok.
+
+- **Praca renderowania po zmianie języka**: Węższe uzupełnienie: ile wysiłku interfejsowi zajęło przepainting dla nowego języka po tym, jak przełączenie jest w locie. Przydatne, gdy „odczuty" czas i koszt framework'u się rozchodzą.
+
+- **Czas początkowego załadowania strony**: Od nawigacji do przeglądarki traktującej stronę jako całkowicie załadowaną dla scenariuszy, które testowałem. Dobry do porównywania zimnych startów.
+
+- **Czas hydratacji**: Gdy aplikacja to ujawnia, jak długo klient spędza na zamienianiu HTML serwera na coś, na co możesz faktycznie kliknąć. Kreska w tabelach oznacza, że implementacja nie dostarczyła wiarygodnej liczby hydratacji w tym benchmarku.
+
 ## Gwiazdki na GitHubie
 
 Gwiazdki na GitHubie są silnym wskaźnikiem popularności projektu, zaufania społeczności i długoterminowego znaczenia. Choć nie są bezpośrednią miarą jakości technicznej, odzwierciedlają, ilu programistów uważa projekt za przydatny, śledzi jego postępy i prawdopodobnie go przyjmie. Przy szacowaniu wartości projektu gwiazdki pomagają porównać zainteresowanie alternatywami i dostarczają wglądu w rozwój ekosystemu.

package/docs/pl/benchmark/svelte.md

@@ -116,6 +116,28 @@ Porównaliśmy **cztery strategie ładowania**:
 - **Scoped static**: Utrzymuje porządek w kodzie (logiczna separacja) bez skomplikowanych dodatkowych zapytań sieciowych.
 - **Scoped dynamic**: Najlepsze podejście dla _code splittingu_ 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, a następnie zapisałem, co faktycznie pojawiło się na sieci i ile czasu to zajęło. Rozmiary są podawane **po normalnej kompresji internetowej**, ponieważ jest to bliższe temu, co ludzie pobierają, niż surowe liczby źródłowe.
+
+- **Rozmiar biblioteki internacjonalizacji**: Po bundlingu, tree-shakingu i minifikacji rozmiar biblioteki i18n to rozmiar kodu dostawców + magazynów w pustym komponencie. Nie obejmuje wczytywania plików tłumaczeń. Odpowiada na pytanie, jak kosztowna jest biblioteka, zanim Twoja zawartość wejdzie na scenę.
+
+- **JavaScript na stronie**: Dla każdej trasy benchmarku, ile skryptu przeglądarka pobiera dla tej wizyty, uśrednione dla stron w zestawie (i dla lokalizacji, gdzie raport je łączy). Ciężkie strony są wolnymi stronami.
+
+- **Wyciek z innych lokalizacji**: To zawartość tej samej strony, ale w innym języku, która byłaby załadowana przez pomyłkę na auditowanej stronie. Ta zawartość jest niepotrzebna i powinna być unikana. (np. zawartość strony `/fr/about` w pakiecie strony `/en/about`)
+
+- **Wyciek z innych tras**: Ten sam pomysł dla **innych ekranów** w aplikacji: czy ich tekst towarzyszy ci, gdy otwierasz tylko jedną stronę. (np. zawartość strony `/en/about` w pakiecie strony `/en/contact`). Wysoki wynik sugeruje słabe dzielenie lub zbyt szerokie pakiety.
+
+- **Średni rozmiar pakietu komponentu**: Popularne elementy interfejsu użytkownika są mierzone **jeden na raz** zamiast ukrywania się wewnątrz jednej gigantycznej liczby aplikacji. Pokazuje, czy internacjonalizacja po cichu inflacyjnie wpływa na codzienne komponenty. Na przykład, jeśli twój komponent się renderuje, załaduje wszystkie te dane z pamięci. Dołączenie gigantycznego JSON-a do dowolnego komponentu to jak podłączenie dużego magazynu nieużywanych danych, który spowolni wydajność twoich komponentów.
+
+- **Responsywność przełącznika języka**: Przełączam język za pomocą własnej kontroli aplikacji i mierzę, ile czasu upłynie, zanim strona wyraźnie się przełączy, co odwiedzający by zauważył, a nie laboratoryjny mikro-krok.
+
+- **Praca renderowania po zmianie języka**: Bardziej zawężone uzupełnienie: ile wysiłku interfejs podjął, aby przemalować dla nowego języka, gdy przełącznik jest w locie. Przydatne, gdy „odczuwany" czas i koszt frameworka się rozbiegają.
+
+- **Czas ładowania początkowej strony**: Od nawigacji do przeglądarki uznającej stronę za w pełni załadowaną dla testowanych scenariuszy. Dobry dla porównywania zimnych startów.
+
+- **Czas hydratacji**: Kiedy aplikacja go ujawnia, jak długo klient spędza na zamienianiu HTML-a serwera w coś, na co faktycznie można kliknąć. Kreska w tabelach oznacza, że ta implementacja nie dostarczyła wiarygodnej liczby hydratacji w tym benchmarku.
+
 ## Gwiazdki na GitHubie
 
 Gwiazdki na GitHubie są silnym wskaźnikiem popularności projektu, zaufania społeczności i długoterminowego znaczenia. Choć nie są bezpośrednią miarą jakości technicznej, odzwierciedlają, ilu programistów uważa projekt za przydatny, śledzi jego postępy i prawdopodobnie go przyjmie. Przy szacowaniu wartości projektu gwiazdki pomagają porównać zainteresowanie alternatywami i dostarczają wglądu w rozwój ekosystemu.

package/docs/pl/benchmark/tanstack.md

@@ -124,6 +124,28 @@ Porównaliśmy **cztery strategie ładowania**:
 - **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 stacku, a następnie zapisałem, co dokładnie pojawiło się na przewodzie i jak długo to trwało. Rozmiary są podawane **po normalnej kompresji sieci web**, ponieważ jest to bliższe temu, co ludzie pobierają, niż surowe liczby źródłowe.
+
+- **Rozmiar biblioteki internationalization**: Po bundlingu, tree-shakingu i minifikacji, rozmiar biblioteki i18n to rozmiar providerów (np. `NextIntlClientProvider`) + kod hooks'ów (np. `useTranslations`) w pustym komponencie. Nie obejmuje to ładowania plików tłumaczeń. Odpowiada na pytanie, jak kosztowna jest biblioteka, zanim Twoja zawartość pojawi się w grze.
+
+- **JavaScript na stronę**: Dla każdej trasy benchmarku, ile skryptu przeglądarka pobiera w tej wizycie, uśrednione na stronach w zestawie (i na locales, gdzie raport je łączy). Ciężkie strony to wolne strony.
+
+- **Wyciek z innych locale'ów**: To zawartość tej samej strony, ale w innym języku, która zostałaby załadowana przez pomyłkę na audytowanej stronie. Ta zawartość jest niepotrzebna i powinna być unikana. (np. zawartość strony `/fr/about` w bundlu strony `/en/about`)
+
+- **Wyciek z innych tras**: Ten sam pomysł dla **innych ekranów** w aplikacji: czy ich zawartość się pojawia, gdy otworzysz tylko jedną stronę. (np. zawartość strony `/en/about` w bundlu strony `/en/contact`). Wysoki wynik wskazuje na słabe splitting'owanie lub zbyt szerokie bundle'e.
+
+- **Średni rozmiar bundle'u komponentu**: Typowe elementy UI są mierzone **pojedynczo** zamiast być ukryte wewnątrz jednej gigantycznej liczby aplikacji. Pokazuje, czy internationalization po cichu nie powiększa codziennych komponentów. Na przykład, jeśli Twój komponent się ponownie renderuje, załaduje wszystkie dane z pamięci. Przyłączenie gigantskiego JSONa do dowolnego komponentu to jak podłączenie dużego magazynu nieużywanych danych, które spowolnią wydajność Twoich komponentów.
+
+- **Responsywność przełączania języka**: Przełączam język za pomocą kontrolki aplikacji i mierzę, jak długo trwa, zanim strona wyraźnie się zmieni, co zauważy odwiedzający, a nie mikro-krok z laboratorium.
+
+- **Praca renderowania po zmianie języka**: Węższe uzupełnienie: ile wysiłku zajęło interfejsowi przerysowanie nowego języka, gdy przełącznik jest w drodze. Przydatne, gdy "odczuwany" czas i koszt frameworka różnią się.
+
+- **Czas ładowania strony początkowej**: Od nawigacji do przeglądarki, która uważa stronę za w pełni załadowaną dla testowanych scenariuszy. Dobry do porównywania zimnych startów.
+
+- **Czas nawodnień (hydration)**: Gdy aplikacja to ujawnia, jak długo klient spędza na zamianie serwera HTML na coś, w co można faktycznie kliknąć. Kreska w tabelach oznacza, że implementacja nie dostarczyła wiarygodnej liczby nawodnienia w tym benchmarku.
+
 ## Gwiazdki na GitHubie
 
 Gwiazdki na GitHubie są silnym wskaźnikiem popularności projektu, zaufania społeczności i długoterminowego znaczenia. Choć nie są bezpośrednią miarą jakości technicznej, odzwierciedlają, ilu programistów uważa projekt za przydatny, śledzi jego postępy i prawdopodobnie go przyjmie. Przy szacowaniu wartości projektu gwiazdki pomagają porównać zainteresowanie alternatywami i dostarczają wglądu w rozwój ekosystemu.

package/docs/pl/cli/ci.md

@@ -140,6 +140,28 @@ steps:
     run: npx intlayer ci fill
 ```
 
+## Wygenerowane GitHub Actions
+
+Gdy uruchomisz `intlayer init`, Intlayer wykrywa Twój package manager (npm, yarn, pnpm lub bun) i generuje dwa przepływy pracy GitHub Actions w `.github/workflows/`, z poleceniami odpowiadającymi tego package managera:
+
+- **`intlayer-fill.yml`** — Na każde pull request, buduje słowniki i uruchamia `intlayer fill --git-diff --mode complete` aby wygenerować brakujące tłumaczenia dla zmienonych słowników, następnie zatwierdza wynik z powrotem do gałęzi PR.
+- **`intlayer-test.yml`** — Na każde pull request, buduje słowniki i uruchamia `intlayer test`, nie powodując sprawdzenia, gdy brakuje wymaganych lokalizacji tłumaczenia.
+
+Istniejące pliki przepływu pracy nigdy nie są zastępowane. Aby całkowicie pominąć scaffolding, uruchom:
+
+```bash
+npx intlayer init --no-github-actions
+```
+
+### Zapewnianie dostępu do AI w workflow fill
+
+Scaffold `intlayer-fill.yml` wymaga dostępu do AI. Dostępne są dwie opcje (skonfigurowane w bloku `env` workflow):
+
+1. **Twój własny klucz dostawcy AI** — Dodaj secret `AI_API_KEY` w ustawieniach repozytorium (Settings → Secrets and variables → Actions). Workflow przekazuje go poprzez `--provider`, `--model` i `--api-key`.
+2. **Klucze dostępu do Intlayer CMS** — Dodaj secrety `INTLAYER_CLIENT_ID` i `INTLAYER_CLIENT_SECRET` i powiąż je z sekcją `editor` w `intlayer.config`. Klucze dostępu do CMS zapewniają dostęp do AI poprzez backend Intlayer.
+
+Workflow `intlayer-test.yml` nie wymaga żadnego dostępu do AI.
+
 ## Obsługa błędów
 
 - Jeśli `INTLAYER_PROJECT_CREDENTIALS` nie jest ustawiona, polecenie zakończy się błędem.

package/docs/pl/cli/fill.md

@@ -47,6 +47,14 @@ Kluczowe punkty:
 - Zachowuje istniejące tłumaczenia, nie nadpisując ich.
 - Przetwarza pliki, fragmenty i lokalizacje równolegle przy użyciu systemu kolejkowego, aby zwiększyć prędkość.
 
+## Kluczowe punkty:
+
+- Dzieli duże pliki JSON na fragmenty, aby pozostać w granicach kontekstu modelu AI.
+- Ponawia tłumaczenie, jeśli format wyjściowy jest nieprawidłowy.
+- Zawiera kontekst specyficzny dla aplikacji i pliku, aby poprawić dokładność tłumaczenia.
+- Zachowuje istniejące tłumaczenia, nie zastępując ich.
+- Przetwarza pliki, fragmenty i lokalizacje równolegle przy użyciu systemu kolejki, aby zwiększyć szybkość.
+
 ## Alias:
 
 - `npx intlayer dictionaries fill`