@intlayer/docs 9.1.3 → 9.3.0

package/docs/pl/analytics.md

@@ -0,0 +1,220 @@
+---
+createdAt: 2026-07-08
+updatedAt: 2026-07-08
+title: Intlayer Analytics | Śledzenie ekspozycji treści i testy A/B
+description: Dowiedz się, w jaki sposób @intlayer/analytics śledzi wyświetlenia stron/języków i ekspozycję treści oraz jak z niego korzystać do przeprowadzania testów A/B zawartości Intlayer.
+keywords:
+  - Analytics (Analityka)
+  - Testy A/B
+  - Odbiorcy (Audience)
+  - Internacjonalizacja
+  - Dokumentacja
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - analytics
+history:
+  - version: 9.0.0
+    date: 2026-07-08
+    changes: "Init doc — pakiet @intlayer/analytics, śledzenie na poziomie dostawcy (provider)/węzła (node), testy A/B, dashboard"
+author: aymericzip
+---
+
+# Dokumentacja Intlayer Analytics
+
+`@intlayer/analytics` to opcjonalny pakiet dodatkowy, który podpowiada ci **jakie treści są faktycznie wyświetlane** twoim odwiedzającym — jaka strona, w jakiej lokalizacji (języku) oraz jaki konkretny fragment przetłumaczonej treści — co pozwala ci lepiej zrozumieć odbiorców i przeprowadzać **testy A/B zawartości**.
+
+## Spis treści
+
+<TOC/>
+
+---
+
+## Co jest śledzone
+
+`@intlayer/analytics` gromadzi i wysyła (batch) trzy rodzaje anonimowych zdarzeń:
+
+| Zdarzenie          | Gdzie przechwytywane                             | Co mówi                                                                                                                                    |
+| ------------------ | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `page_view`        | Na poziomie Providera (`IntlayerProvider`)       | Jaką stronę i lokalizację (locale) przeglądała sesja podczas pierwszego ładowania, zmiany trasy lub zmiany lokalizacji.                    |
+| `content_exposure` | Na poziomie Węzła (`useIntlayer` / interpretery) | Jaki klucz słownika / ścieżka klucza został faktycznie rozwiązany i wyświetlony — oraz, jeśli jest częścią eksperymentu, jaki **wariant**. |
+| `conversion`       | Gdziekolwiek wywołasz `useConversion()`          | Cel osiągnięty (rejestracja, kliknięcie, zakup...) przypisany do wariantu A/B, na który została wystawiona sesja.                          |
+
+Zdarzenia są zbierane w pamięci i wysyłane jako **jedno żądanie wsadowe (batch request) w przybliżeniu co 20 sekund** — nigdy po każdym wciśnięciu klawisza czy renderowaniu — więc analityka nigdy nie wpływa na czas pierwszego wyrenderowania ani nie dodaje żądań dla każdej interakcji.
+
+## Jak napędza to testy A/B treści
+
+Intlayer pozwala ci już deklarować [Warianty (Variants)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dynamic_dictionaries/index.md) zawartości (np. słownik `hero-banner` z wariantem `control` i `black_friday`). `@intlayer/analytics` zamyka pętlę:
+
+1. `getVariant(experimentKey, variants)` deterministycznie przypisuje każdą anonimową sesję do danego wariantu — czysta funkcja bazująca na identyfikatorze sesji i kluczu eksperymentu, więc przypisanie jest **stabilne przez całą sesję** i nie wymaga **okrężnego zapytania do serwera (server round-trip)** przed pierwszym wyrenderowaniem (brak migotania, brak przesunięć układu/layout shift).
+2. Każde zdarzenie `content_exposure` przenosi `variant`, który został pokazany.
+3. `useConversion()` pozwala na przypisanie celu (np. `"cta_click"`) do tego wariantu.
+4. Punkt końcowy (endpoint) z wynikami eksperymentu na dashboardzie porównuje współczynniki konwersji (conversion rates) wariantów, wliczając w to istotność statystyczną (test-z).
+
+## Instalacja
+
+`@intlayer/analytics` jest zależnością typu **peer, opcjonalną** — nigdy nie jest instalowana automatycznie przez żaden pakiet frameworku. Dodaj ją obok `intlayer`:
+
+```bash packageManager="npm"
+npm install @intlayer/analytics
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/analytics
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/analytics
+```
+
+```bash packageManager="bun"
+bun add @intlayer/analytics
+```
+
+Jeśli nie ją zainstalujesz, każdy punkt integracyjny sprowadza się do pustej operacji (no-op) — zobacz [Zerowy koszt, gdy nie zainstalowano](#zerowy-koszt-gdy-nie-zainstalowano) poniżej.
+
+## Konfiguracja
+
+Analytics **wykorzystuje ponownie istniejący blok konfiguracji `editor`** — nie ma osobnego schematu konfiguracyjnego `analytics` do uzupełnienia:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  editor: {
+    backendURL: "https://back.intlayer.org", // Wykorzystywane również jako punkt końcowy przyswajania analityki
+    clientId: "your-client-id", // Wykorzystywane również jako klucz projektu analityki
+    clientSecret: "your-client-secret",
+  },
+};
+
+export default config;
+```
+
+- `editor.backendURL` — podstawowy URL, do którego przesyłane są zdarzenia analityki (`POST {backendURL}/api/analytics/events`).
+- `editor.clientId` — publiczny klucz projektu przypisany do każdego przetworzonego zdarzenia. Służy również jako **przełącznik aktywacji**: analityka pozostaje całkowicie wyłączona (oraz usunięta podczas tree-shakingu, patrz niżej), dopóki `clientId` nie zostanie skonfigurowany.
+
+Jeśli hostujesz sam Intlayer (self-host), analityka automatycznie wskazuje na twoją własną instancję, jako że współdzieli parametr `editor.backendURL`.
+
+## Wsparcie dla Frameworków
+
+Analytics jest wpięty w udostępniony `IntlayerProvider` z `react-intlayer`, stąd jest dostępny już dziś w każdym miejscu, w którym ten provider jest używany:
+
+| Framework                                                | Status                                                                                               |
+| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| React                                                    | ✅ Dostępne                                                                                          |
+| Next.js (`next-intlayer`)                                | ✅ Dostępne (poprzez `react-intlayer`)                                                               |
+| React Native / Expo (`react-native-intlayer`)            | ✅ Dostępne (poprzez `react-intlayer`)                                                               |
+| Vue, Svelte, Angular, Solid, Preact, Lit, Astro, Vanilla | 🚧 Zaplanowano — ten sam klient, podpięcia na poziomie providera wzorujące się na `@intlayer/editor` |
+
+## Użycie
+
+### Automatyczne śledzenie na poziomie providera
+
+Brak konieczności modyfikowania kodu. Po zainstalowaniu pakietu `@intlayer/analytics` oraz po skonfigurowaniu `editor.clientId`, `IntlayerProvider` będzie automatycznie:
+
+- inicjalizować klienta analityki po zamontowaniu (mount),
+- rejestrować `page_view` po pierwszym załadowaniu,
+- rejestrować `page_view` za każdą zmianą lokalizacji,
+- uruchamiać cykl „wypychania” (flush) zdarzeń po około 20 sekundach oraz natychmiast, gdy zakładka zostanie zamknięta (za pośrednictwem `navigator.sendBeacon`, z trybem zapasowym (fallback) do `fetch(..., { keepalive: true })`).
+
+### Automatyczne śledzenie na poziomie węzła
+
+Za każdym razem, gdy `useIntlayer` rozwiąże jakiś fragment treści do wyświetlenia, interpreter raportuje zdarzenie typu `content_exposure` dla odpowiedniego elementu tj. zbiór `dictionaryKey` + lokalizacja (locale) + precyzyjna ścieżka klucza (key path) — ponownie, nie ma potrzeby zmieniania kodu. Powielone zdarzenia tego samego węzła pojawiające się w cyklu wypychania zostają zgrupowane do 1 zapytania razem z właściwością `count` — dzięki czemu lista z renderowaniem wykonywanym po 50 razy nie wypycha 50 razy osobnego zapytania.
+
+### Śledzenie konwersji do testów A/B
+
+Wykorzystaj `useConversion()`, aby przypisać cel do wariantu, z którym wchodzono w interakcję w czasie sesji:
+
+```tsx fileName="CTAButton.tsx" codeFormat="tsx"
+import { useConversion } from "react-intlayer";
+
+const CTAButton = () => {
+  const trackConversion = useConversion();
+
+  return (
+    <button
+      onClick={() =>
+        trackConversion({
+          experimentKey: "homepage-hero",
+          variant: "black_friday",
+          goal: "cta_click",
+        })
+      }
+    >
+      Rozpocznij
+    </button>
+  );
+};
+```
+
+### Odbieranie wariantu bezpośrednio po stronie klienta
+
+```tsx fileName="useHeroVariant.ts" codeFormat="tsx"
+import { getGlobalAnalyticsClient } from "@intlayer/analytics/client";
+
+const client = getGlobalAnalyticsClient();
+const variant = client?.getVariant("homepage-hero", [
+  "control",
+  "black_friday",
+]);
+```
+
+## Prywatność & Wydajność
+
+- **Z założenia anonimowe (Anonymous by design)**: sesje definiowane są losowymi unikalnymi indentyfikatorami (rotating ids), i backend nie przetwarza danych tak mocno, by przetrzymywać oryginał i nigdy IP urządzenia; pozostawia jedynie odcienie, zjawisko **SHA-256 hash**.
+- **Dokładność pozycjonowania ogólna (coarse)**: pozostaje do dyspozycji jedynie unikalny fragment kraju.
+- **Odnośniki odrzucają query string (search params)** z definicji.
+- **Losowanie pul (Sampling)**: opcja `sampleRate` umożliwia selekcjonowanie wyświetlanej treści.
+- **Zbiorcze transakcje (Batched)**: 1 transakcja średnio na 20 sec (`flushInterval`), w skrajnych momentach częściej, np. by wyzerować zapętlające procesy, jeżeli dojdzie do uzupełniania bufru (`maxBufferSize`).
+
+### Zerowy koszt, gdy nie zainstalowano
+
+`@intlayer/analytics` podąża za tym samym modelem zależności opcjonalnej co `@intlayer/editor`:
+
+- Zawsze paczka dociągana jest dynamicznie w osłonie **`import()` z klauzulą `try/catch`**.
+- Stała wartość dla buildowania (`INTLAYER_ANALYTICS_ENABLED`) redukuje procesowanie w kodzie zjawiskiem **dead-code-eliminate** do momentu skonfigurowania i deklaracji `editor.clientId`.
+
+## Dashboard: Strona Analityki
+
+Jak tylko system zdobędzie niezbędne detale na start z Twojego portalu (podpiętego pod projekt), sekcja **Analytics** (pod panelem) ukaże widok:
+
+- Ilość użytkowników „Aktywnych”.
+- Sumę w danym przedziale do ok 7 dni.
+- Widok wyświetleń z perspektywy danej grupy stron (Page views).
+- Pełen zakres podziału z punktu widzenia specyficznych preferencji odwiedzającego – w oparciu o sekcje państw z dodatkiem preferowanych ustawień językowych na zakładce podziału.
+
+## Odniesienie Backend API
+
+Każde odniesienie czytające poddawane jest procesom weryfikacyjnym. System pobierający wystawiony jest na świat by funkcjonować prawidłowo z argumentem body `clientId`.
+
+| Metoda | Endpoint                                    | Opis                                                                                |
+| ------ | ------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `POST` | `/api/analytics/events`                     | Masowe pobieranie eventów z puli publicznej odfiltrowane wg. kryteriów `clientId`.  |
+| `GET`  | `/api/analytics/overview`                   | Parametry odsłon na język i podstrony do autoryzowanego projektu.                   |
+| `GET`  | `/api/analytics/audience?days=30`           | Grupy wizytorów i szczegóły wyświetlania w ujęciu wielowymiarowym (dzień,język,itd) |
+| `GET`  | `/api/analytics/content-stats`              | Odsłony w grupie precyzyjnie celowanej ścieżki i pod klucz w słowniku.              |
+| `GET`  | `/api/analytics/experiments/:experimentKey` | Konwersja by przeprowadzać na wariantach testy (A/B testing, statistical itp.)      |
+
+Korzystając z dostępu masz uprawnienia do podpięcia własnych wywoływań ze skryptami wspierając system SDK: [CMS SDK](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/intlayer_CMS.md):
+
+```ts fileName="analytics.ts"
+import { createIntlayerCMS } from "@intlayer/api";
+import { analyticsEndpoint } from "@intlayer/api/analytics";
+
+const cms = createIntlayerCMS();
+
+const { data: audience } = await analyticsEndpoint(cms).getAudience(30);
+```
+
+## Przydatne linki
+
+- [Słowniki dynamiczne – Kolekcje & Warianty (Dynamic Dictionaries)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dynamic_dictionaries/index.md)
+- [Intlayer CMS - CMS SDK](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/intlayer_CMS.md)
+- [Intlayer Visual Editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/intlayer_visual_editor.md)
+- [Odwołanie konfiguracyjne (Configuration Reference)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/configuration.md)
+- [Poradnik hostingu samodzielnego (Self-Hosting Guide)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/self_hosting.md)

package/docs/pl/bundle_optimization.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-11-25
-updatedAt: 2026-06-07
+updatedAt: 2026-08-09
 title: Optymalizacja Rozmiaru Paczki i Wydajności i18n
 description: Zmniejsz rozmiar paczki swojej aplikacji, optymalizując treści umiędzynarodowienia (i18n). Dowiedz się, jak wykorzystać tree shaking i leniwe ładowanie (lazy loading) dla słowników dzięki Intlayer.
 keywords:
@@ -16,6 +16,12 @@ slugs:
   - concept
   - bundle-optimization
 history:
+  - version: 9.2.1
+    date: 2026-08-09
+    changes: "`purge` i `minify` działają teraz w Next.js poprzez `@intlayer/swc` — plik `babel.config.js` nie jest wymagany"
+  - version: 8.12.0
+    date: 2026-06-24
+    changes: "Wypisanie wtyczek Babel w wymaganej kolejności potoku (extract → purge → minify → optimize) w tabelach referencyjnych"
   - version: 8.12.0
     date: 2026-06-07
     changes: "Dodano `intlayerPurgeBabelPlugin` i `intlayerMinifyBabelPlugin` dla Babel/Webpack; wyjaśnienie działania przepływu wtyczek (pipeline)"
@@ -191,12 +197,14 @@ Optymalizacja w trakcie budowania przez Intlayer podzielona jest na kilka niezal
 
 Wtyczki te są wykorzystywane bezpośrednio w `babel.config.js` dla środowisk opartych na Webpacku (Next.js z Babel, CRA, własne konfiguracje Webpack itp.).
 
+Poniższa tabela wymienia je w wymaganej kolejności potoku (tej samej, w jakiej muszą wystąpić w `babel.config.js`):
+
 | Wtyczka                       | Działanie                                                                                                               |
 | :---------------------------- | :---------------------------------------------------------------------------------------------------------------------- |
 | `intlayerExtractBabelPlugin`  | Skanuje pliki `.content.ts` i zapisuje skompilowane słowniki w katalogu `.intlayer/`                                    |
-| `intlayerOptimizeBabelPlugin` | Przepisuje kod `useIntlayer('key')` → `useDictionary(hash)` i wstrzykuje import pasującego słownika                     |
 | `intlayerPurgeBabelPlugin`    | Skanuje wszystkie pliki źródłowe, usuwając **nieużywane pola treści** ze skompilowanych słowników `.intlayer/**/*.json` |
 | `intlayerMinifyBabelPlugin`   | **Zmienia nazwy kluczy pól treści** na krótkie, literowe aliasy (np. `title` → `a`) w plikach JSON i kodzie źródłowym   |
+| `intlayerOptimizeBabelPlugin` | Przepisuje kod `useIntlayer('key')` → `useDictionary(hash)` i wstrzykuje import pasującego słownika                     |
 
 > **Kolejność wtyczek ma znaczenie.** W Twoim `babel.config.js` wtyczki purge i minify muszą pojawić się **przed** wtyczką optimize. Krok optymalizacji zastępuje bowiem `useIntlayer('key')` nieprzejrzystym wywołaniem `useDictionary(hash)`, usuwając informację o kluczu słownika. Właśnie tej informacji potrzebują etapy purge i minify, aby móc określić, które pola są wykorzystywane.
 
@@ -205,9 +213,9 @@ Każda z wtyczek dla Babel ma swój dedykowany helper dla opcji, który odczytuj
 | Helper opcji                 | Zastosowanie z wtyczką        |
 | :--------------------------- | :---------------------------- |
 | `getExtractPluginOptions()`  | `intlayerExtractBabelPlugin`  |
-| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
 | `getPurgePluginOptions()`    | `intlayerPurgeBabelPlugin`    |
 | `getMinifyPluginOptions()`   | `intlayerMinifyBabelPlugin`   |
+| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
 
 ### Wtyczki Vite (`vite-intlayer`)
 
@@ -220,6 +228,20 @@ Użytkownicy Vite **nigdy nie konfigurują ich bezpośrednio**. Są one podłąc
 | Dictionary minify       | Działa jak etap zapisu JSON we wtyczce `intlayerMinifyBabelPlugin`                               |
 | Babel transform         | Działa jak etap zmiany nazewnictwa z `intlayerMinifyBabelPlugin` + `intlayerOptimizeBabelPlugin` |
 
+### Wtyczka SWC (`@intlayer/swc`)
+
+Użytkownicy Next.js również **nigdy nie konfigurują tego bezpośrednio**. Od wersji **9.2.1** `withIntlayer()` w `next.config.ts` uruchamia cały potok — purge, minifikację i przepisywanie importów — wyłącznie na podstawie flag `build.purge` i `build.minify`.
+
+Praca jest podzielona na dwie części, ponieważ wtyczka Wasm SWC przekształca jeden plik naraz i nie ma dostępu do systemu plików:
+
+| Przebieg                                               | Gdzie działa                    | Co robi                                                                                             |
+| :----------------------------------------------------- | :------------------------------ | :-------------------------------------------------------------------------------------------------- |
+| Analiza użycia + purge/minifikacja JSON                | Node, wewnątrz `withIntlayer()` | Czyta każdy plik źródłowy komponentu, przepisuje `.intlayer/**/*.json` i tworzy tablice zmiany nazw |
+| Przepisywanie kodu źródłowego (`content.title` → `.a`) | `@intlayer/swc` (Wasm)          | Stosuje tablice zmiany nazw do odpowiadających odwołań do właściwości w Twoim kodzie                |
+| Przepisywanie importów (`useIntlayer` → dict)          | `@intlayer/swc` (Wasm)          | Tak samo jak `intlayerOptimizeBabelPlugin`                                                          |
+
+Ustalenie, _które_ pola są nieużywane i _jaki_ alias otrzyma każde z nich, wymaga stanu obejmującego wiele plików oraz operacji wejścia/wyjścia na plikach, więc ta połowa działa w Node; wtyczka SWC otrzymuje jedynie wynikowe tablice.
+
 ## Konfiguracja wg Platformy
 
 <Tabs>
@@ -227,10 +249,12 @@ Użytkownicy Vite **nigdy nie konfigurują ich bezpośrednio**. Są one podłąc
 
 ### Next.js
 
-Next.js wymaga instalacji wtyczki `@intlayer/swc` na etapie optymalizacji (przepisywania importów), ponieważ Next.js wykorzystuje do budowania SWC.
+Next.js wymaga wtyczki `@intlayer/swc`, ponieważ Next.js używa SWC do budowania. Od wersji **9.2.1** ten jeden pakiet obsługuje cały potok — optymalizację (przepisywanie importów), purge i minifikację.
 
 > Ta wtyczka nie jest instalowana domyślnie, ponieważ wtyczki SWC dla Next.js mają wciąż charakter eksperymentalny. Może się to zmienić w przyszłości.
 
+> **Next.js 16.1.0 to wersja minimalna.** To pierwsze wydanie zbudowane na zgodnym w przód ABI wtyczek Wasm SWC; wcześniejsze wydania odrzucają wtyczkę. `withIntlayer` odczytuje Twoją wersję Next.js i po prostu nie rejestruje wtyczki poniżej 16.1.0 — takie buildy nadal się udają, po prostu działają bez optymalizacji bundla.
+
 <Tabs>
  <Tab value="npm">
 
@@ -265,33 +289,40 @@ intlayer-swc-plugin = "*"
 
 Po jej zainstalowaniu Intlayer automatycznie wykryje i wykorzysta tę wtyczkę.
 
-Do przejścia etapów **purge i minify** (usuwania i skracania pól), należy zainstalować równolegle `@intlayer/babel` i dodać wtyczki Babel. Choć Next.js do transformacji korzysta z SWC, wciąż interpretuje `babel.config.js` w zakresie konfiguracji wtyczek, co sprawia, że wtyczki dla Babel uruchamiane są jeszcze przed etapem SWC.
+Przebiegi **purge i minifikacji** (usuwanie i zmiana nazw pól) nie wymagają dodatkowego pakietu ani pliku `babel.config.js`. Owiń swoją konfigurację funkcją `withIntlayer` i włącz flagi w `intlayer.config.ts`:
 
-```bash packageManager="npm"
-npm install -D @intlayer/babel
+```typescript fileName="next.config.ts"
+import { withIntlayer } from "next-intlayer/server";
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {/* twoja konfiguracja */};
+
+export default withIntlayer(nextConfig);
 ```
 
-```javascript fileName="babel.config.js"
-const {
-  intlayerPurgeBabelPlugin,
-  intlayerMinifyBabelPlugin,
-  getPurgePluginOptions,
-  getMinifyPluginOptions,
-} = require("@intlayer/babel");
+```typescript fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
 
-module.exports = {
-  presets: ["next/babel"],
-  plugins: [
-    // Purge: usuwa nieużywane pola ze słowników z .intlayer/**/*.json
-    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],
-    // Minify: skraca nazwy kluczy w polach w plikach JSON i kodzie źródłowym
-    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],
-    // Uwaga: intlayerOptimizeBabelPlugin NIE JEST TUTAJ POTRZEBNY, ponieważ
-    // to @intlayer/swc obsługuje zastępowanie useIntlayer → useDictionary.
-  ],
+const config: IntlayerConfig = {
+  build: {
+    purge: true, // usuwa nieużywane pola treści z dołączonego JSON-a
+    minify: true, // zmienia klucze pól treści na krótkie aliasy
+  },
 };
+
+export default config;
 ```
 
+Podczas `next build` `withIntlayer` analizuje Twoje źródła, przepisuje skompilowane słowniki i przekazuje wynikowe tablice zmiany nazw pól do `@intlayer/swc`, które aktualizuje odpowiadające odwołania do właściwości w Twoim kodzie.
+
+> Używaj asynchronicznego `withIntlayer`, a nie `withIntlayerSync`. Wariant synchroniczny nie uruchamia potoku analizy, więc purge i minifikacja nie mają z nim żadnego efektu.
+
+> Purge i minifikacja działają tylko przy `next build` — potok optymalizacji jest wyłączony podczas `next dev`.
+
+> Są też wyłączone, gdy skonfigurowano wywołujących z adapterów kompatybilności (`swcExtraCallers`, ustawiane przez pakiety kompatybilności takie jak `@intlayer/next-intl` czy `@intlayer/react-i18next`): te miejsca wywołań są niewidoczne dla analizatora użycia, więc purge usunąłby pola, które kod nadal odczytuje. Przepisywanie importów pozostaje aktywne.
+
+**Wcześniejsze wersje (przed 9.2.1)** wymagały `@intlayer/babel` oraz pliku `babel.config.js` deklarującego `intlayerPurgeBabelPlugin` i `intlayerMinifyBabelPlugin`. Ten plik nie jest już potrzebny i można go usunąć.
+
  </Tab>
  <Tab value="vite">
 
@@ -447,6 +478,8 @@ export default config;
 
 > Krok dla minifikacji musi zostać oddalony w odstawkę, gdy Twoja opcja to `optimize` lub jeżeli udostępniasz systemowo `editor.enabled` i ustawiasz na domyślne `true` (wymuszone jest, aby pola trzymały na ten czas swe niezmącone relacje, dla potrzeb odpowiedniego renderowania Wizualnego Edytora).
 
+> W Next.js minifikacja jest również pomijana, gdy `@intlayer/swc` nie jest zainstalowany albo nie może zostać załadowany (Next.js poniżej 16.1.0). Wtyczka to ta połowa, która przepisuje odwołania w kodzie źródłowym, więc zmiana nazw w słownikach bez niej pozostawiłaby kod odczytujący nazwy pól, które już nie istnieją.
+
 > Ten sam manewr odłożenia ma miejsce w słownikach przywoływanych jako typ opcji z użyciem `importMode: 'fetch'`, gdzie zawarte odpowiedzi napływają niezwłocznie dzięki połączonemu formatowi JSON. Gdyby zastosowano sztuczne przeinaczenie ze stron zewnętrznych, serwer stałby się bezużyteczny z perspektywy klienta i połącznie zostałoby połamane.
 
 ### Purging (Usuwanie Nieużytych Przestrzeni)
@@ -475,7 +508,7 @@ export default config;
 { "title": "…", "subtitle": "…" }
 ```
 
-> Mechanizm obalenia Purge opiera się głównie o pominięcia w wypadku kiedy brakuje `optimize` opcjonalnej flagi tudzież podczas zadeklarowania trybu pod system Visual Editor (ustawiając `editor.enabled` na rzecz trybu `true`).
+> Mechanizm obalenia Purge opiera się głównie o pominięcia w wypadku kiedy brakuje `optimize` opcjonalnej flagi tudzież podczas zadeklarowania trybu pod system Visual Editor (ustawiając `editor.enabled` na rzecz trybu `true`). W Next.js jest dodatkowo pomijany, gdy `@intlayer/swc` jest niedostępny oraz gdy skonfigurowano wywołujących z adapterów kompatybilności.
 
 > Co rzadsze zjawiska również tyczą się tego obejścia - dla niemożności sprawdzenia wycinka czy pospolitych struktur dla `useIntlayer` - silnik bezbłędnie zablokuje akcję. Przykładowo dla wywołań w niejednoznacznych tablicach powiązanych metod bez destrukturyzacji by zachować słownikową formę naturalną.
 

package/docs/pl/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-07-11
+updatedAt: 2026-08-06
 title: Konfiguracja
 description: Dowiedz się, jak skonfigurować Intlayer dla swojej aplikacji. Zrozum różne ustawienia i opcje dostępne do dostosowania Intlayer do Twoich potrzeb.
 keywords:
@@ -14,6 +14,9 @@ slugs:
   - concept
   - configuration
 history:
+  - version: 9.1.3
+    date: 2026-08-06
+    changes: "Uczynienie `routing.enableProxy` trójstanowym: nieustawione (auto), `true`, `false`"
   - version: 9.0.0
     date: 2026-07-11
     changes: "Dodano konfigurację `analytics`"
@@ -235,6 +238,19 @@ const config: IntlayerConfig = {
      */
     mode: "prefix-no-default",
 
+    /**
+     * Włącza proxy routingu lokalizacji Intlayer (middleware).
+     * Obsługuje wykrywanie lokalizacji, przekierowania i przepisywanie w dev, preview i SSR.
+     * - nieustawione (auto): serwery dev i preview utrzymują routing sterowany adresem URL,
+     *   ignorując lokalizację zapisaną w ciasteczkach i nagłówkach. Prefiksy nadal są
+     *   rozwiązywane, lokalizacja nadal jest zapisywana, a wykrywanie Accept-Language
+     *   nadal działa. W produkcji zachowuje się jak `true`.
+     * - true: pełne zachowanie w każdym środowisku.
+     * - false: brak routingu lokalizacji.
+     * Domyślnie: undefined (auto)
+     */
+    enableProxy: undefined,
+
     /**
      * Miejsce przechowywania locale wybranego przez użytkownika.
      * Opcje: 'cookie', 'localStorage', 'sessionStorage', 'header' lub ich tablica.
@@ -713,13 +729,14 @@ Analityka jest ściśle opt-in: nic nie jest zbierane, dopóki `analytics.enable
 
 Ustawienia kontrolujące zachowanie routingu, w tym strukturę URL, przechowywanie locale i obsługę middleware.
 
-| Pole       | Opis                                                                                                                                                                                                           | Typ                                                                                                                                                                                                          | Domyślnie              | Przykład                                                                                                                                                                                | Uwagi                                                                                                                                                                                                                                                                              |
-| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mode`     | Tryb struktury URL do zarządzania locale.                                                                                                                                                                      | `'prefix-no-default'` &#124; <br/> `'prefix-all'` &#124; <br/> `'no-prefix'` &#124; <br/> `'search-params'`                                                                                                  | `'prefix-no-default'`  | `'prefix-no-default'`: `/dashboard` (en) lub `/fr/dashboard` (fr). `'prefix-all'`: `/en/dashboard`. `'no-prefix'`: locale zarządzane inaczej. `'search-params'`: `/dashboard?locale=fr` | Nie wpływa na zarządzanie plikami cookie ani pamięcią lokalną.                                                                                                                                                                                                                     |
-| `storage`  | Konfiguracja przechowywania locale u klienta.                                                                                                                                                                  | `false` &#124; <br/> `'cookie'` &#124; <br/> `'localStorage'` &#124; <br/> `'sessionStorage'` &#124; <br/> `'header'` &#124; <br/> `CookiesAttributes` &#124; <br/> `StorageAttributes` &#124; <br/> `Array` | `['cookie', 'header']` | `'localStorage'` <br/> `[{ type: 'cookie', name: 'custom-locale', secure: true }]`                                                                                                      | Zobacz tabelę opcji przechowywania poniżej.                                                                                                                                                                                                                                        |
-| `basePath` | Bazowa ścieżka dla adresów URL aplikacji.                                                                                                                                                                      | `string`                                                                                                                                                                                                     | `''`                   | `'/my-app'`                                                                                                                                                                             | Jeśli Twoja aplikacja znajduje się pod adresem `https://example.com/my-app`, basePath to `'/my-app'`, co wskazuje na URL `https://example.com/my-app/en`.                                                                                                                          |
-| `rewrite`  | Własne reguły przepisywania URL w celu zmiany domyślnego trybu routingu dla określonych ścieżek. Obsługuje parametry dynamiczne `[param]`.                                                                     | `Record<string, StrictModeLocaleMap<string>>`                                                                                                                                                                | `undefined`            | Zobacz przykład poniżej                                                                                                                                                                 | • Reguły routingu mają wyższy priorytet niż `mode`.<br/>• Działa z Next.js i Vite.<br/>• `getLocalizedUrl()` automatycznie stosuje pasujące reguły.<br/>• Zobacz [Własne przepisywanie URL](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/custom_url_rewrites.md). |
-| `domains`  | Mapuje locale na nazwy hostów domen dla routingu opartego na domenach. Gdy ustawione, adresy URL dla danego locale używają tej domeny jako bazy (absolutny URL) i do ścieżki nie jest dodawany prefiks locale. | `Partial<Record<Locale, string>>`                                                                                                                                                                            | `undefined`            | `{ zh: 'intlayer.zh', fr: 'intlayer.org' }`                                                                                                                                             | • Domyślnym protokołem jest `https://`, gdy nie jest zawarty w nazwie hosta.<br/>• Sama domena identyfikuje locale, więc prefiks `/zh/` nie jest dodawany.<br/>• `getLocalizedUrl('/', 'zh')` zwraca `https://intlayer.zh/`.                                                       |
+| Pole          | Opis                                                                                                                                                                                                           | Typ                                                                                                                                                                                                          | Domyślnie              | Przykład                                                                                                                                                                                | Uwagi                                                                                                                                                                                                                                                                                                                                                                                        |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`        | Tryb struktury URL do zarządzania locale.                                                                                                                                                                      | `'prefix-no-default'` &#124; <br/> `'prefix-all'` &#124; <br/> `'no-prefix'` &#124; <br/> `'search-params'`                                                                                                  | `'prefix-no-default'`  | `'prefix-no-default'`: `/dashboard` (en) lub `/fr/dashboard` (fr). `'prefix-all'`: `/en/dashboard`. `'no-prefix'`: locale zarządzane inaczej. `'search-params'`: `/dashboard?locale=fr` | Nie wpływa na zarządzanie plikami cookie ani pamięcią lokalną.                                                                                                                                                                                                                                                                                                                               |
+| `enableProxy` | Włącza proxy routingu lokalizacji Intlayer (middleware).                                                                                                                                                       | `boolean` &#124; <br/> `undefined`                                                                                                                                                                           | `undefined` (auto)     | `true`                                                                                                                                                                                  | • Nieustawione (auto): serwery dev i preview ignorują lokalizację zapisaną w ciasteczkach/nagłówkach jako źródło przekierowania; prefiksy, zapisywanie i wykrywanie `Accept-Language` nadal działają. W produkcji zachowuje się jak `true`.<br/>• `true`: pełne zachowanie wszędzie.<br/>• `false`: brak routingu lokalizacji. W Next.js middleware `intlayerProxy` staje się przezroczysty. |
+| `storage`     | Konfiguracja przechowywania locale u klienta.                                                                                                                                                                  | `false` &#124; <br/> `'cookie'` &#124; <br/> `'localStorage'` &#124; <br/> `'sessionStorage'` &#124; <br/> `'header'` &#124; <br/> `CookiesAttributes` &#124; <br/> `StorageAttributes` &#124; <br/> `Array` | `['cookie', 'header']` | `'localStorage'` <br/> `[{ type: 'cookie', name: 'custom-locale', secure: true }]`                                                                                                      | Zobacz tabelę opcji przechowywania poniżej.                                                                                                                                                                                                                                                                                                                                                  |
+| `basePath`    | Bazowa ścieżka dla adresów URL aplikacji.                                                                                                                                                                      | `string`                                                                                                                                                                                                     | `''`                   | `'/my-app'`                                                                                                                                                                             | Jeśli Twoja aplikacja znajduje się pod adresem `https://example.com/my-app`, basePath to `'/my-app'`, co wskazuje na URL `https://example.com/my-app/en`.                                                                                                                                                                                                                                    |
+| `rewrite`     | Własne reguły przepisywania URL w celu zmiany domyślnego trybu routingu dla określonych ścieżek. Obsługuje parametry dynamiczne `[param]`.                                                                     | `Record<string, StrictModeLocaleMap<string>>`                                                                                                                                                                | `undefined`            | Zobacz przykład poniżej                                                                                                                                                                 | • Reguły routingu mają wyższy priorytet niż `mode`.<br/>• Działa z Next.js i Vite.<br/>• `getLocalizedUrl()` automatycznie stosuje pasujące reguły.<br/>• Zobacz [Własne przepisywanie URL](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/custom_url_rewrites.md).                                                                                                           |
+| `domains`     | Mapuje locale na nazwy hostów domen dla routingu opartego na domenach. Gdy ustawione, adresy URL dla danego locale używają tej domeny jako bazy (absolutny URL) i do ścieżki nie jest dodawany prefiks locale. | `Partial<Record<Locale, string>>`                                                                                                                                                                            | `undefined`            | `{ zh: 'intlayer.zh', fr: 'intlayer.org' }`                                                                                                                                             | • Domyślnym protokołem jest `https://`, gdy nie jest zawarty w nazwie hosta.<br/>• Sama domena identyfikuje locale, więc prefiks `/zh/` nie jest dodawany.<br/>• `getLocalizedUrl('/', 'zh')` zwraca `https://intlayer.zh/`.                                                                                                                                                                 |
 
 **Przykład `rewrite`**:
 

package/docs/pl/dictionary/nesting.md

@@ -68,6 +68,53 @@ export default firstDictionary;
 }
 ```
 
+### Odwołania się z Nest
+
+Teraz utwórz inny moduł zawartości, który używa funkcji `nest` do odwołania się do powyższej zawartości. Możesz odwołać się do całej zawartości lub do określonej wartości zagnieżdżonej:
+
+```typescript fileName="secondDictionary.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+import { nest, type Dictionary } from "intlayer";
+
+const myNestingContent = {
+  key: "key_of_my_second_dictionary",
+  content: {
+    // Odwołanie do całego słownika:
+    fullNestedContent: nest("key_of_my_first_dictionary"),
+    // Odwołanie do określonej wartości zagnieżdżonej:
+    partialNestedContent: nest(
+      "key_of_my_first_dictionary",
+      "subContent.contentNumber"
+    ),
+  },
+} satisfies Dictionary;
+
+export default myNestingContent;
+```
+
+```json fileName="secondDictionary.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "key_of_my_second_dictionary",
+  "content": {
+    "fullNestedContent": {
+      "nodeType": "nested",
+      "nested": {
+        "dictionaryKey": "key_of_my_first_dictionary"
+      }
+    },
+    "partialNestedContent": {
+      "nodeType": "nested",
+      "nested": {
+        "dictionaryKey": "key_of_my_first_dictionary",
+        "path": "subContent.contentNumber"
+      }
+    }
+  }
+}
+```
+
+Jako drugi parametr możesz określić ścieżkę do wartości zagnieżdżonej w ramach tej zawartości. Jeśli nie zostanie podana żadna ścieżka, zwracana jest cała zawartość odwoływanego słownika.
+
 ## Konfiguracja zagnieżdżania
 
 <Tabs group="framework">
@@ -262,36 +309,6 @@ document.getElementById("nested")!.textContent = content.partialNestedContent;
   </Tab>
 </Tabs>
 
-## Używanie zagnieżdżenia z React Intlayer
-
-Aby użyć zagnieżdżonej zawartości w komponencie React, skorzystaj z hooka `useIntlayer` z pakietu `react-intlayer`. Ten hook pobiera odpowiednią zawartość na podstawie podanego klucza. Oto przykład, jak go użyć:
-
-```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
-import type { FC } from "react";
-import { useIntlayer } from "react-intlayer";
-
-const NestComponent: FC = () => {
-  const { fullNestedContent, partialNestedContent } = useIntlayer(
-    "key_of_my_second_dictionary"
-  );
-
-  return (
-    <div>
-      <p>
-        Full Nested Content: {JSON.stringify(fullNestedContent)}
-        {/* Wynik: {"content": "content", "subContent": {"contentNumber": 0, "contentString": "string"}} */}
-      </p>
-      <p>
-        Częściowa wartość zagnieżdżona: {partialNestedContent}
-        {/* Wynik: 0 */}
-      </p>
-    </div>
-  );
-};
-
-export default NestComponent;
-```
-
 ## Dodatkowe zasoby
 
 Aby uzyskać bardziej szczegółowe informacje na temat konfiguracji i użytkowania, zapoznaj się z następującymi zasobami: