@intlayer/docs 9.4.1 → 9.4.3

package/docs/pl/bundle_optimization.md

@@ -43,139 +43,6 @@ Na przykład, aplikacja z 10 stronami przetłumaczonymi na 10 języków może sp
 
 <TOC />
 
-## Przeanalizuj swoją paczkę
-
-Analiza paczki jest pierwszym krokiem do zidentyfikowania "ciężkich" plików JSON i możliwości dzielenia kodu (code-splitting). Narzędzia te generują wizualną mapę drzewa (treemap) skompilowanego kodu aplikacji, co pozwala precyzyjnie zobaczyć, które biblioteki zajmują najwięcej miejsca.
-
-<Tabs>
- <Tab value="vite">
-
-### Vite / Rollup
-
-Vite pod maską korzysta z Rollup. Wtyczka `rollup-plugin-visualizer` generuje interaktywny plik HTML, który pokazuje rozmiar każdego modułu w grafie.
-
-```bash
-npm install -D rollup-plugin-visualizer
-```
-
-```typescript fileName="vite.config.ts"
-import { defineConfig } from "vite";
-import { visualizer } from "rollup-plugin-visualizer";
-
-export default defineConfig({
-  plugins: [
-    visualizer({
-      open: true, // Automatycznie otwórz raport w przeglądarce
-      filename: "stats.html",
-      gzipSize: true,
-      brotliSize: true,
-    }),
-  ],
-});
-```
-
- </Tab>
- <Tab value="nextjs (turbopack)">
-
-### Next.js (Turbopack)
-
-Dla projektów korzystających z App Routera i Turbopack, Next.js oferuje wbudowany, eksperymentalny analizator, który nie wymaga dodatkowych zależności.
-
-```bash packageManager='npm'
-npx next experimental-analyze
-```
-
-```bash packageManager='yarn'
-yarn next experimental-analyze
-```
-
-```bash packageManager='pnpm'
-pnpm next experimental-analyze
-```
-
-```bash packageManager='bun'
-bun next experimental-analyze
-```
-
- </Tab>
- <Tab value="nextjs (Webpack)">
-
-### Next.js (Webpack)
-
-Jeśli w Next.js korzystasz z domyślnego bundlera Webpack, użyj oficjalnego bundle analyzera. Aktywuje się go, ustawiając odpowiednią zmienną środowiskową w trakcie budowania.
-
-```bash packageManager='npm'
-npm install -D @next/bundle-analyzer
-```
-
-```bash packageManager='yarn'
-yarn add -D @next/bundle-analyzer
-```
-
-```bash packageManager='pnpm'
-pnpm add -D @next/bundle-analyzer
-```
-
-```bash packageManager='bun'
-bun add -d @next/bundle-analyzer
-```
-
-```javascript fileName="next.config.js"
-const withBundleAnalyzer = require("@next/bundle-analyzer")({
-  enabled: process.env.ANALYZE === "true",
-});
-
-module.exports = withBundleAnalyzer({
-  // Twoja konfiguracja Next.js
-});
-```
-
-**Użycie:**
-
-```bash
-ANALYZE=true npm run build
-```
-
- </Tab>
- <Tab value="Webpack (CRA / Angular / etc)">
-
-### Standardowy Webpack
-
-Dla Create React App (po wykonaniu eject), Angular lub niestandardowych konfiguracji Webpack użyj branżowego standardu `webpack-bundle-analyzer`.
-
-```bash packageManager='npm'
-npm install -D webpack-bundle-analyzer
-```
-
-```bash packageManager='yarn'
-yarn add -D webpack-bundle-analyzer
-```
-
-```bash packageManager='pnpm'
-pnpm add -D webpack-bundle-analyzer
-```
-
-```bash packageManager='bun'
-bun add -d webpack-bundle-analyzer
-```
-
-```typescript fileName="webpack.config.ts"
-import { BundleAnalyzerPlugin } from "webpack-bundle-analyzer";
-
-export default {
-  plugins: [
-    new BundleAnalyzerPlugin({
-      analyzerMode: "static",
-      reportFilename: "bundle-analyzer.html",
-      openAnalyzer: false,
-    }),
-  ],
-};
-```
-
- </Tab>
-</Tabs>
-
 ## Jak to Działa
 
 Intlayer wykorzystuje **podejście per-komponent**. W przeciwieństwie do globalnych plików JSON, Twoje treści są definiowane obok komponentów lub wewnątrz nich. Podczas procesu budowania Intlayer wykonuje następujące czynności:
@@ -189,59 +56,6 @@ Gwarantuje to, że:
 - Jeśli komponent nie zostanie zaimportowany, jego treść nie zostanie dołączona do paczki (Dead Code Elimination).
 - Jeśli komponent ładuje się leniwie (lazy-loaded), jego zawartość również ładuje się w ten sam sposób.
 
-## Informacje o Wtyczkach
-
-Optymalizacja w trakcie budowania przez Intlayer podzielona jest na kilka niezależnych wtyczek, z których każda odpowiada za jedno zadanie. Zrozumienie roli poszczególnych wtyczek zapobiegnie nieporozumieniom podczas ich konfiguracji.
-
-### Wtyczki Babel (`@intlayer/babel`)
-
-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/`                                    |
-| `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.
-
-Każda z wtyczek dla Babel ma swój dedykowany helper dla opcji, który odczytuje `intlayer.config.ts` tylko raz (podczas wczytywania konfiguracji) i zwraca wstępnie rozwiązane wartości:
-
-| Helper opcji                 | Zastosowanie z wtyczką        |
-| :--------------------------- | :---------------------------- |
-| `getExtractPluginOptions()`  | `intlayerExtractBabelPlugin`  |
-| `getPurgePluginOptions()`    | `intlayerPurgeBabelPlugin`    |
-| `getMinifyPluginOptions()`   | `intlayerMinifyBabelPlugin`   |
-| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
-
-### Wtyczki Vite (`vite-intlayer`)
-
-Użytkownicy Vite **nigdy nie konfigurują ich bezpośrednio**. Są one podłączane automatycznie po wywołaniu `withIntlayer()` w pliku `vite.config.ts`. Flagi `build.purge` i `build.minify` umieszczone w `intlayer.config.ts` przełączają ich zachowanie bez potrzeby dodatkowego rejestrowania wtyczek.
-
-| Wewnętrzna wtyczka Vite | Odpowiednik zachowania                                                                           |
-| :---------------------- | :----------------------------------------------------------------------------------------------- |
-| Usage analyzer          | Działa jak etap skanowania wtyczki `intlayerPurgeBabelPlugin`                                    |
-| Dictionary prune        | Działa jak etap zapisu JSON we wtyczce `intlayerPurgeBabelPlugin`                                |
-| 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>
@@ -405,6 +219,59 @@ module.exports = {
  </Tab>
 </Tabs>
 
+## Informacje o Wtyczkach
+
+Optymalizacja w trakcie budowania przez Intlayer podzielona jest na kilka niezależnych wtyczek, z których każda odpowiada za jedno zadanie. Zrozumienie roli poszczególnych wtyczek zapobiegnie nieporozumieniom podczas ich konfiguracji.
+
+### Wtyczki Babel (`@intlayer/babel`)
+
+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/`                                    |
+| `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.
+
+Każda z wtyczek dla Babel ma swój dedykowany helper dla opcji, który odczytuje `intlayer.config.ts` tylko raz (podczas wczytywania konfiguracji) i zwraca wstępnie rozwiązane wartości:
+
+| Helper opcji                 | Zastosowanie z wtyczką        |
+| :--------------------------- | :---------------------------- |
+| `getExtractPluginOptions()`  | `intlayerExtractBabelPlugin`  |
+| `getPurgePluginOptions()`    | `intlayerPurgeBabelPlugin`    |
+| `getMinifyPluginOptions()`   | `intlayerMinifyBabelPlugin`   |
+| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
+
+### Wtyczki Vite (`vite-intlayer`)
+
+Użytkownicy Vite **nigdy nie konfigurują ich bezpośrednio**. Są one podłączane automatycznie po wywołaniu `withIntlayer()` w pliku `vite.config.ts`. Flagi `build.purge` i `build.minify` umieszczone w `intlayer.config.ts` przełączają ich zachowanie bez potrzeby dodatkowego rejestrowania wtyczek.
+
+| Wewnętrzna wtyczka Vite | Odpowiednik zachowania                                                                           |
+| :---------------------- | :----------------------------------------------------------------------------------------------- |
+| Usage analyzer          | Działa jak etap skanowania wtyczki `intlayerPurgeBabelPlugin`                                    |
+| Dictionary prune        | Działa jak etap zapisu JSON we wtyczce `intlayerPurgeBabelPlugin`                                |
+| 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
 
 Możesz kontrolować, w jaki sposób Intlayer optymalizuje Twoją paczkę poprzez propercję `build` w pliku `intlayer.config.ts`.
@@ -649,3 +516,136 @@ const content = useDictionaryAsync({
 | **Asysty Pobrań z Sieci**  | Wolny od błagania o pobrania w locie z sieci.   | Standard to zawsze stosunek 1 klucza.                       |
 | **Warianty Oddzielania**   | Stricte ukierunkowany formą Komponentowych rel. | Łączący wektory z wariantów lokalizacji.                    |
 | **Zalety Po Zastosowaniu** | Drobne platformy z lekkim wymogiem na front.    | Giganty publikujące wpisy z tytanicznym formatem językowym. |
+
+## Przeanalizuj swoją paczkę
+
+Analiza paczki jest najbardziej bezpośrednim sposobem na zidentyfikowanie "ciężkich" plików JSON i możliwości dzielenia kodu (code-splitting). Narzędzia te generują wizualną mapę drzewa (treemap) skompilowanego kodu aplikacji, co pozwala precyzyjnie zobaczyć, które biblioteki zajmują najwięcej miejsca.
+
+<Tabs>
+ <Tab value="vite">
+
+### Vite / Rollup
+
+Vite pod maską korzysta z Rollup. Wtyczka `rollup-plugin-visualizer` generuje interaktywny plik HTML, który pokazuje rozmiar każdego modułu w grafie.
+
+```bash
+npm install -D rollup-plugin-visualizer
+```
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { visualizer } from "rollup-plugin-visualizer";
+
+export default defineConfig({
+  plugins: [
+    visualizer({
+      open: true, // Automatycznie otwórz raport w przeglądarce
+      filename: "stats.html",
+      gzipSize: true,
+      brotliSize: true,
+    }),
+  ],
+});
+```
+
+ </Tab>
+ <Tab value="nextjs (turbopack)">
+
+### Next.js (Turbopack)
+
+Dla projektów korzystających z App Routera i Turbopack, Next.js oferuje wbudowany, eksperymentalny analizator, który nie wymaga dodatkowych zależności.
+
+```bash packageManager='npm'
+npx next experimental-analyze
+```
+
+```bash packageManager='yarn'
+yarn next experimental-analyze
+```
+
+```bash packageManager='pnpm'
+pnpm next experimental-analyze
+```
+
+```bash packageManager='bun'
+bun next experimental-analyze
+```
+
+ </Tab>
+ <Tab value="nextjs (Webpack)">
+
+### Next.js (Webpack)
+
+Jeśli w Next.js korzystasz z domyślnego bundlera Webpack, użyj oficjalnego bundle analyzera. Aktywuje się go, ustawiając odpowiednią zmienną środowiskową w trakcie budowania.
+
+```bash packageManager='npm'
+npm install -D @next/bundle-analyzer
+```
+
+```bash packageManager='yarn'
+yarn add -D @next/bundle-analyzer
+```
+
+```bash packageManager='pnpm'
+pnpm add -D @next/bundle-analyzer
+```
+
+```bash packageManager='bun'
+bun add -d @next/bundle-analyzer
+```
+
+```javascript fileName="next.config.js"
+const withBundleAnalyzer = require("@next/bundle-analyzer")({
+  enabled: process.env.ANALYZE === "true",
+});
+
+module.exports = withBundleAnalyzer({
+  // Twoja konfiguracja Next.js
+});
+```
+
+**Użycie:**
+
+```bash
+ANALYZE=true npm run build
+```
+
+ </Tab>
+ <Tab value="Webpack (CRA / Angular / etc)">
+
+### Standardowy Webpack
+
+Dla Create React App (po wykonaniu eject), Angular lub niestandardowych konfiguracji Webpack użyj branżowego standardu `webpack-bundle-analyzer`.
+
+```bash packageManager='npm'
+npm install -D webpack-bundle-analyzer
+```
+
+```bash packageManager='yarn'
+yarn add -D webpack-bundle-analyzer
+```
+
+```bash packageManager='pnpm'
+pnpm add -D webpack-bundle-analyzer
+```
+
+```bash packageManager='bun'
+bun add -d webpack-bundle-analyzer
+```
+
+```typescript fileName="webpack.config.ts"
+import { BundleAnalyzerPlugin } from "webpack-bundle-analyzer";
+
+export default {
+  plugins: [
+    new BundleAnalyzerPlugin({
+      analyzerMode: "static",
+      reportFilename: "bundle-analyzer.html",
+      openAnalyzer: false,
+    }),
+  ],
+};
+```
+
+ </Tab>
+</Tabs>

package/docs/pl/configuration.md

@@ -1121,3 +1121,101 @@ Kontroluje ustawienia kompilatora Intlayer, który kolekcjonuje słowniki bezpo
 | Pole      | Opis                                              | Typ                |
 | --------- | ------------------------------------------------- | ------------------ |
 | `plugins` | Lista wtyczek Intlayer, które mają być dołączone. | `IntlayerPlugin[]` |
+
+## Często Zadawane Pytania
+
+<FAQ>
+
+<Question title="Gdzie powinien znajdować się plik intlayer.config.ts?">
+
+W katalogu głównym projektu, obok `package.json`. Intlayer przeszukuje katalog roboczy i jego katalogi nadrzędne w poszukiwaniu `intlayer.config.ts`, `intlayer.config.js`, `intlayer.config.mjs` lub `intlayer.config.cjs`. Możesz również wskazać niestandardową ścieżkę za pomocą flagi `--config` w poleceniach CLI.
+
+</Question>
+
+<Question title="O ile i18n zwiększa rozmiar mojego bundle'a?">
+
+Znacznie mniej niż rozwiązania oparte na przestrzeniach nazw, ponieważ strona nigdy nie pobiera katalogu, którego nie renderuje. Znaczniki renderowane po stronie serwera rozwiązują treść na serwerze, a kompilator czasu budowy zastępuje wywołania `useIntlayer` dokładnymi wpisami, których używa komponent, dzięki czemu nieużywane klucze i nieużywane języki są usuwane. [Słowniki dynamiczne](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dynamic_dictionaries/index.md) dzielą resztę na poszczególne języki. W porównaniu z typowymi alternatywami, Intlayer zmniejsza rozmiar bundle'a i strony nawet o 50%. Zobacz [optymalizację bundle'a](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/bundle_optimization.md) oraz [benchmark](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/benchmark/index.md).
+
+</Question>
+
+<Question title="Czy mogę zmigrować z i18next, next-intl lub react-i18next bez przepisywania moich komponentów?">
+
+Tak, i są dwie drogi. Możesz migrować treść stopniowo za pomocą [przewodnika migracji z i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/migration_from_i18next_to_intlayer.md) lub [przewodnika migracji z next-intl](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/migration_from_next-intl_to_intlayer.md). Możesz także zachować obecne API w całości: [adaptery kompatybilności](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/compat/index.md) udostępniają dokładnie to samo API co `i18next`, `react-i18next`, `next-intl`, `next-i18next`, `react-intl`, `use-intl`, `vue-i18n` i `Lingui`, ale zasilane słownikami Intlayer, więc zmieniają się importy, a kod komponentów pozostaje nienaruszony.
+
+</Question>
+
+<Question title="Czy mogę zachować moje istniejące pliki tłumaczeń JSON?">
+
+Tak. Wtyczka [sync JSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/plugins/sync-json.md) utrzymuje Twoje pliki `/messages/{locale}/{namespace}.json` jako źródło prawdy i generuje z nich słowniki Intlayer w obu kierunkach. Wtyczka [sync PO](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/plugins/sync-po.md) robi to samo dla katalogów gettext, a [pliki per locale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/per_locale_file.md) pozwalają rozdzielić zawartość według języka zamiast grupować lokalizacje w jednym pliku.
+
+</Question>
+
+<Question title="Czy muszę przenosić moją zawartość klucz po kluczu?">
+
+Nie. Uruchom `npx intlayer extract`, a Intlayer odczyta Twoje pliki źródłowe, wyodrębni ciągi widoczne dla użytkownika i utworzy plik `.content` obok każdego z nich, dzięki czemu przeglądasz diff zamiast ręcznie kopiować ciągi do katalogu pojedynczo. Zobacz [polecenie extract](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/cli/extract.md).
+
+W przypadku w pełni zautomatyzowanego procesu [Intlayer Compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/compiler.md) robi to samo w czasie budowania w kodzie JSX, TSX, Vue i Svelte, generując słowniki przy każdej zmianie, dzięki czemu nie ma potrzeby ręcznego zarządzania kluczami. Działa on w oparciu o analizę statyczną, więc ciągi istniejące tylko w czasie wykonywania pozostają poza jego zasięgiem i wymaga kilku adnotacji do odróżnienia tekstu dla użytkownika od logiki aplikacji.
+
+</Question>
+
+<Question title="Jakie narzędzia dla edytora i agentów AI są dostępne?">
+
+Pięć narzędzi, wszystkie opcjonalne:
+
+- **[Rozszerzenie VS Code](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/vs_code_extension.md)**: przejście od klucza `useIntlayer` do pliku treści, który go deklaruje, wyodrębnianie treści z komponentu oraz uruchamianie build, fill, test, push i pull z palety poleceń lub dedykowanej karty Intlayer.
+- **[Serwer LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/lsp.md)**: taka sama świadomość w dowolnym edytorze obsługującym LSP, z funkcjami przejdź do definicji (go to definition), znajdź wszystkie referencje, podglądem przetłumaczonej wartości po najechaniu kursorem, autouzupełnianiem kluczy i pól oraz ostrzeżeniem, gdy klucz nie jest nigdzie zadeklarowany. Rozpoznaje również wywołania `i18next`, `react-i18next`, `next-intl` i `use-intl`, co ułatwia migrację.
+- **[Serwer MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/mcp_server.md)**: udostępnia dokumentację i CLI Intlayer dla Cursor, VS Code, Claude Desktop, Claude Code i ChatGPT, dzięki czemu asystent odpowiada na podstawie aktualnej dokumentacji zamiast zgadywać i może samodzielnie wykonywać polecenia, takie jak `intlayer fill`.
+- **[Umiejętności agenta (Agent skills)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/agent_skills.md)**: wyspecjalizowane umiejętności, takie jak `intlayer-config`, `intlayer-cli` i `intlayer-content`, oraz po jednej dla każdego frameworka, które uczą agenta konfiguracji routingu i typów węzłów treści.
+- **[Wtyczka ESLint](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/eslint.md)**: reguła `no-raw-text` oznacza zakodowane na stałe ciągi tekstowe, z dodatkowymi regułami dla statycznych kluczy słownika i nieużywanej zawartości.
+
+</Question>
+
+<Question title="Jak dodać nowy język do mojej aplikacji?">
+
+Dodaj kod języka do tablicy `internationalization.locales`, a następnie uruchom `npx intlayer fill`, aby przetłumaczyć na niego istniejącą treść za pomocą AI. Kompilator automatycznie uwzględni nowy język przy następnym uruchomieniu.
+
+</Question>
+
+<Question title="Jak usunąć prefiks języka z moich adresów URL?">
+
+Ustaw `routing.mode`. Wartość `"no-prefix"` usuwa prefiks języka dla wszystkich lokalizacji, określając aktywny język na podstawie ciasteczka, nagłówka lub domeny. Wartość `"prefix-no-default"` (domyślna) usuwa prefiks tylko dla języka domyślnego, zachowując go dla pozostałych.
+
+</Question>
+
+<Question title="Czy mogę serwować każdy język z jego własnej domeny?">
+
+Tak. Opcja `routing.domains` mapuje każdą lokalizację na nazwę hosta, na przykład `{ pl: 'example.pl', en: 'example.com' }`. Identyfikacja domeny ma pierwszeństwo przed prefiksami ścieżek, a `getMultilingualUrls` generuje pełne adresy URL w metadanych `hreflang`.
+
+</Question>
+
+<Question title="W jaki sposób wykrywany jest język użytkownika?">
+
+Poprzez `routing.storage`, które określa źródła w kolejności ważności: zazwyczaj najpierw URL, potem ciasteczko, a następnie nagłówek `Accept-Language`, powracając do domyślnego języka.
+
+</Question>
+
+<Question title="Co robi opcja routing.enableProxy?">
+
+Kontroluje proxy routingu językowego: middleware, który obsługuje prefiksy i przekierowania. Pozostawiona pusta automatycznie uruchamia proxy w trybie deweloperskim i produkcyjnym. Ustawienie `false` wyłącza je całkowicie, jeśli samodzielnie zarządzasz trasowaniem.
+
+</Question>
+
+<Question title="Jaka jest różnica między importMode static, dynamic i fetch?">
+
+Wartość `"static"` (domyślna) importuje słowniki statycznie, więc są one pakowane do bundle'a i odczytywane synchronicznie. Wartość `"dynamic"` importuje słowniki asynchronicznie per język, redukując początkowy rozmiar bundle'a. Wartość `"fetch"` pobiera słowniki z serwera lub CMS w czasie działania.
+
+</Question>
+
+<Question title="Gdzie ustawić dostawcę AI i klucz API dla automatycznego tłumaczenia?">
+
+W pliku konfiguracyjnym w sekcji `ai` lub w wierszu poleceń za pomocą flag `--provider`, `--model` i `--api-key`. Klucz pozostaje po Twojej stronie i nigdy nie opuszcza Twojego środowiska. Zobacz [dokumentację konfiguracji AI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/configuration.md).
+
+</Question>
+
+<Question title="Czy muszę restartować serwer deweloperski po zmianie konfiguracji?">
+
+Zazwyczaj nie. Watcher Intlayer obserwuje plik `intlayer.config.ts`: po zapisaniu przeładowuje konfigurację i przygotowuje słowniki w tle.
+
+</Question>
+
+</FAQ>

package/docs/pl/dictionary/content_file.md

@@ -366,15 +366,15 @@ Przekształca słownik w słownik per-lokalizacyjny, gdzie każde pole zadeklaro
 
 **Przykład:**
 
-```json
+```jsonc
 // Słownik per-locale
 {
   "key": "about-page",
   "locale": "en",
   "content": {
     "title": "About Us", // To staje się węzłem tłumaczenia dla 'en'
-    "description": "Learn more about our company"
-  }
+    "description": "Learn more about our company",
+  },
 }
 ```
 
@@ -444,7 +444,7 @@ Instrukcje dotyczące automatycznego wypełniania zawartości słownika z zewnę
 
 **Przykłady:**
 
-```json
+```jsonc
 // Wyłącz wypełnianie
 {
   "fill": false

package/docs/pl/dictionary/markdown.md

@@ -51,6 +51,7 @@ Możesz zadeklarować treść Markdown używając funkcji `md` lub po prostu jak
 
 <Tabs>
   <Tab label=".content.md" value=".content.md">
+
     Począwszy od wersji `8.10.0`, możesz deklarować treść Markdown bezpośrednio w plikach `.content.md`. Intlayer automatycznie wykryje i przetworzy treść Markdown.
 
     ```md fileName="markdown-file.en.content.md"
@@ -96,6 +97,7 @@ Możesz zadeklarować treść Markdown używając funkcji `md` lub po prostu jak
     ```
 
   </Tab>
+
   <Tab label="Pliki zewnętrzne" value="external-files">
     Importuj pliki `.md` bezpośrednio za pomocą funkcji `file`.
 
@@ -129,6 +131,7 @@ Możesz zadeklarować treść Markdown używając funkcji `md` lub po prostu jak
     ```
 
   </Tab>
+
 </Tabs>
 
 ## Renderowanie Markdown

package/docs/pl/dictionary/plurial.md

@@ -35,9 +35,12 @@ W przeciwieństwie do [`enu`](https://github.com/aymericzip/intlayer/blob/main/d
 
 ## Kiedy używać `plural` vs `enu`
 
-To use plural content inside a React component, retrieve it via the `useIntlayer` hook and call it with a count. The active locale and the count are combined to pick the matching CLDR category.
+| Przypadek użycia                                                              | Pomocnik |
+| ----------------------------------------------------------------------------- | -------- |
+| Gramatyczne formy liczby mnogiej zależne od języka (jabłko / jabłka / jabłek) | `plural` |
+| Niestandardowe zakresy liczbowe (`<5`, `>=10`) lub kategorie spoza CLDR       | `enu`    |
 
-To use plural content in Next.js Client Components, retrieve it via the `useIntlayer` hook and call it with a count. Here's an example:
+Jeśli tworzysz aplikację tylko po angielsku (gdzie występuje tylko `one` / `other`), oba rozwiązania zadziałają. W przypadku języków z rozróżnieniem `few` / `many` / `two`, preferuj `plural`.
 
 ## Konfigurowanie treści w liczbie mnogiej