@intlayer/docs 8.12.5-canary.0 → 9.0.0-canary.10

package/docs/pl/packages/vite-intlayer/intlayerProxy.md

@@ -0,0 +1,172 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: Dokumentacja wtyczki Vite intlayerProxy | vite-intlayer
+description: Oprogramowanie pośredniczące (middleware) do routingu języków dla serwerów deweloperskich i podglądu Vite oraz produkcyjnego SSR. Obsługuje wykrywanie języka, przekierowania URL i wewnętrzne przepisywanie ścieżek.
+keywords:
+  - intlayerProxy
+  - vite
+  - wtyczka
+  - middleware
+  - język
+  - routing
+  - umiędzynarodowienie
+  - i18n
+  - SSR
+slugs:
+  - doc
+  - packages
+  - vite-intlayer
+  - intlayerProxy
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "Scalono configOptions w jeden obiekt opcji; proxy jest wbudowane w intlayer()"
+author: aymericzip
+---
+
+# intlayerProxy
+
+`intlayerProxy` to wtyczka Vite, która rejestruje oprogramowanie pośredniczące (middleware) do routingu języków dla **każdego środowiska**: serwera deweloperskiego, serwera podglądu i produkcyjnego SSR (Nitro / TanStack Start).
+
+> **Od Intlayer v9** `intlayerProxy` jest automatycznie dołączany do głównej wtyczki [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/vite-intlayer/intlayer.md) i domyślnie włączony poprzez `routing.enableProxy: true`. Musisz go zarejestrować osobno tylko wtedy, gdy potrzebujesz kontroli na niższym poziomie lub używasz go poza standardową konfiguracją `intlayer()`.
+
+## Użycie
+
+### Jako część `intlayer()` (zalecane, v9+)
+
+Przekaż opcje `proxy` do głównej wtyczki zamiast rejestrować `intlayerProxy` osobno:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
+});
+```
+
+### Samodzielnie (w razie potrzeby)
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+## Opcje
+
+```ts
+import type { IntlayerProxyPluginOptions } from "vite-intlayer";
+```
+
+Wszystkie opcje są opcjonalne i przekazywane jako pojedynczy obiekt:
+
+| Opcja           | Typ                                 | Opis                                                                                                                                                                     |
+| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ignore`        | `(req: IncomingMessage) => boolean` | Predykat wykluczający żądania z routingu języków. Zwróć `true`, aby pominąć żądanie (np. ścieżki API, testy kondycji/health checki).                                     |
+| `configOptions` | `GetConfigurationOptions`           | Nadpisania konfiguracji Intlayer przekazywane do `getConfiguration()`. Użyj, gdy potrzebujesz, aby proxy czytało określony plik konfiguracyjny lub nadpisywało wartości. |
+
+### Przykład
+
+```ts
+intlayerProxy({
+  ignore: (req) => req.url?.startsWith("/api"),
+  configOptions: { configFile: "./config/intlayer.config.ts" },
+});
+```
+
+## createIntlayerProxyHandler
+
+`createIntlayerProxyHandler` tworzy samodzielne, niezależne od frameworka oprogramowanie pośredniczące Node.js `(req, res, next)`, które zawiera całą logikę routingu języków. Jest przydatne w środowiskach, w których API wtyczek Vite jest niedostępne (np. czysty serwer Node.js lub niestandardowy moduł Nitro).
+
+```ts
+import { createIntlayerProxyHandler } from "vite-intlayer";
+
+const handler = createIntlayerProxyHandler({
+  ignore: (req) => req.url?.startsWith("/api"),
+  configOptions: { configFile: "./config/intlayer.config.ts" },
+});
+
+// Express / Connect
+app.use(handler);
+```
+
+### Produkcyjny SSR (TanStack Start / Nitro przez h3)
+
+```ts
+// server/middleware/intlayerProxy.ts
+import { fromNodeMiddleware } from "h3";
+import { createIntlayerProxyHandler } from "vite-intlayer";
+
+export default fromNodeMiddleware(
+  createIntlayerProxyHandler({
+    ignore: (req) => req.url?.startsWith("/api"),
+  })
+);
+```
+
+## Zachowanie routingu
+
+Oprogramowanie pośredniczące odzwierciedla logikę routingu z middleware `next-intlayer` i obsługuje wszystkie tryby routingu Intlayer.
+
+### Tryby routingu
+
+| Tryb            | Widoczność URL w przeglądarce | Zachowanie                                                                                                                                                          |
+| --------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `prefix`        | `/pl/about`                   | Domyślny. Prefiks języka w adresie URL. Domyślny język przekierowuje do adresu URL bez prefiksu, chyba że włączono `prefix-all`.                                    |
+| `prefix-all`    | `/en/about`, `/pl/about`      | Wszystkie języki — w tym domyślny — są zawsze poprzedzone prefiksem.                                                                                                |
+| `no-prefix`     | `/about`                      | Brak języka w adresie URL. Język jest przechowywany wyłącznie w plikach cookie; przepisywanie URL odbywa się wewnętrznie.                                           |
+| `search-params` | `/about?locale=pl`            | Język przekazywany jako parametr zapytania (query parameter). Przekierowuje w celu dodania/aktualizacji parametru `locale`, jeśli go brakuje lub jest przestarzały. |
+
+### Priorytet wykrywania
+
+1. Prefiks ścieżki URL (np. `/pl/about` → `pl`).
+2. Wartość pliku cookie / localStorage (`intlayer-locale`).
+3. Nagłówek `Accept-Language`.
+4. `defaultLocale` z konfiguracji.
+
+### Automatyczne pomijanie (bypass)
+
+Oprogramowanie pośredniczące zawsze przepuszcza te żądania bezpośrednio, bez obsługi języka:
+
+- Żądania pasujące do predykatu `ignore`.
+- `/node_modules/**`
+- `/@**` – wewnętrzne zasoby Vite (`@vite/`, `@fs/`, `@id/` itp.).
+- `/_**` – wewnętrzne zasoby serwera (`__vite_ping`, `__manifest` itp.).
+- Żądania, których ścieżka kończy się rozszerzeniem pliku (zasoby statyczne). Jeśli w ścieżce zasobu statycznego obecny jest prefiks języka (np. `/pl/logo.png`), zostaje on usunięty, aby plik mógł być serwowany poprawnie.
+
+### Routing domenowy
+
+Gdy w konfiguracji Intlayer skonfigurowano `routing.domains`, oprogramowanie pośredniczące obsługuje routing językowy między różnymi domenami:
+
+- Żądanie dla `/zh/about` w domenie `intlayer.org` jest przekierowywane na `https://intlayer.zh/about`, gdy `domains.zh = "intlayer.zh"`.
+- Żądanie do `intlayer.zh/about` jest wewnętrznie przepisywane na `/zh/about`, aby parametr trasy `[locale]` został uzupełniony.
+
+### Ochrona przed pętlą przekierowań
+
+Oprogramowanie pośredniczące śledzi liczbę przekierowań dla pary `originalUrl → newUrl` w ruchomym oknie 2 sekund. Więcej niż 10 przekierowań w tym oknie zwraca odpowiedź `500` z opisowym błędem zamiast zapętlania się w nieskończoność.
+
+## Nitro / produkcyjny SSR (automatyczna iniekcja, v9+)
+
+Gdy `intlayerProxy` jest używany jako wtyczka Vite, niesie ze sobą właściwość `.nitro`. Wtyczka budująca `nitro/vite` odczytuje tę właściwość i wstrzykuje ją do `nitroConfig.modules`, dzięki czemu `intlayerNitroHandler` rejestruje się jako serwerowe oprogramowanie pośredniczące Nitro automatycznie — dla produkcyjnego SSR nie jest wymagana żadna ręczna konfiguracja.
+
+Handler Nitro korzysta z modelu zdarzeń Web Fetch API h3 v2 (nie `fromNodeMiddleware`), więc jest kompatybilny ze wszystkimi szablonami (presets) Nitro: Node, Bun, Deno, środowiskami edge.
+
+## Zdeprecjonowane aliasy
+
+| Zdeprecjonowany eksport    | Zamiennik       |
+| -------------------------- | --------------- |
+| `intlayerMiddleware`       | `intlayerProxy` |
+| `intLayerMiddlewarePlugin` | `intlayerProxy` |

package/docs/pl/packages/vue-intlayer/exports.md

@@ -14,6 +14,9 @@ slugs:
   - vue-intlayer
   - exports
 history:
+  - version: 10.0.0
+    date: 2026-06-23
+    changes: "Dodanie narzędzia usePathname"
   - version: 8.0.0
     date: 2026-01-21
     changes: "Ujednolicona dokumentacja dla wszystkich eksportów"
@@ -59,6 +62,7 @@ import "vue-intlayer";
 | `useDictionaryAsync`   | Tak jak `useDictionary`, ale obsługuje asynchroniczne słowniki.                                                                                            | -                                                                                                                     |
 | `useDictionaryDynamic` | Tak jak `useDictionary`, ale obsługuje dynamiczne słowniki.                                                                                                | -                                                                                                                     |
 | `useLocale`            | Zwraca bieżący locale oraz funkcję do jego ustawienia.                                                                                                     | -                                                                                                                     |
+| `usePathname`          | Zwraca bieżący pathname jako `ComputedRef<string>` z usuniętym segmentem locale. Reaguje na zdarzenia `popstate`.                                          | [usePathname](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/vue-intlayer/usePathname.md)     |
 | `useRewriteURL`        | Composable po stronie klienta do zarządzania przepisywaniem adresów URL. Automatycznie aktualizuje URL, jeśli istnieje zlokalizowana reguła przepisywania. | [useRewriteURL](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/vue-intlayer/useRewriteURL.md) |
 | `useIntl`              | Zwraca obiekt Intl dla bieżącej lokalizacji.                                                                                                               | -                                                                                                                     |
 | `useLoadDynamic`       | Composable do ładowania dynamicznych słowników.                                                                                                            | -                                                                                                                     |

package/docs/pl/packages/vue-intlayer/usePathname.md

@@ -0,0 +1,109 @@
+---
+createdAt: 2026-06-22
+updatedAt: 2026-06-22
+title: Dokumentacja funkcji usePathname | vue-intlayer
+description: Dowiedz się, jak korzystać z funkcji usePathname z pakietu vue-intlayer
+keywords:
+  - usePathname
+  - pathname
+  - locale
+  - Intlayer
+  - Internacjonalizacja
+  - Dokumentacja
+  - Vue
+  - JavaScript
+slugs:
+  - doc
+  - packages
+  - vue-intlayer
+  - usePathname
+history:
+  - version: 10.0.0
+    date: 2026-06-23
+    changes: "Dodanie narzędzia usePathname"
+  - version: 8.2.0
+    date: 2026-06-22
+    changes: "Inicjalizacja historii"
+author: aymericzip
+---
+
+# Integracja Vue: Dokumentacja `usePathname`
+
+Funkcja `usePathname` zwraca obecny pathname przeglądarki z usuniętym segmentem locale, w postaci `ComputedRef<string>` z Vue. Jest to przydatne do budowy nawigacji uwzględniającej locale — na przykład, aby określić, który element nawigacji jest aktywny — bez konieczności ręcznego usuwania prefiksu locale.
+
+## Importowanie `usePathname` w Vue
+
+```typescript
+import { usePathname } from "vue-intlayer";
+```
+
+## Przegląd
+
+`usePathname` tworzy Vue computed ref, który odczytuje `window.location.pathname`, usuwa prefiks locale za pomocą `getPathWithoutLocale`, i aktualizuje swoją wartość za każdym razem, gdy przeglądarka wywoła zdarzenie `popstate` (nawigacja wstecz/dalej). Ta wartość może być używana bezpośrednio w Twoich szablonach Vue lub funkcjach setup.
+
+## Użycie
+
+```vue fileName="src/components/NavItem.vue"
+<script setup lang="ts">
+import { usePathname } from "vue-intlayer";
+
+const props = defineProps<{
+  href: string;
+  label: string;
+}>();
+
+const pathname = usePathname();
+</script>
+
+<template>
+  <a :href="href" :aria-current="pathname === href ? 'page' : undefined">
+    {{ label }}
+  </a>
+</template>
+```
+
+## Zwracana Wartość
+
+| Typ                   | Opis                                                                                            |
+| --------------------- | ----------------------------------------------------------------------------------------------- |
+| `ComputedRef<string>` | Obiekt typu Computed Ref z Vue, zawierający obecny pathname z przeglądarki bez prefiksu locale. |
+
+## Zachowanie
+
+- **Usuwanie locale**: Usuwa wiodący segment locale (np. `/pl/dashboard` → `/dashboard`).
+- **Reaktywność**: Aktualizuje wartość przy każdym zdarzeniu `popstate` (nawigacja wstecz / do przodu w przeglądarce).
+- **Bezpieczne dla SSR**: Zwraca `""`, gdy `window` nie jest dostępne.
+- **Czyszczenie (Cleanup)**: Nasłuchiwacz (listener) `popstate` jest dodawany globalnie podczas inicjalizacji i zazwyczaj nie wymaga ręcznego czyszczenia na poziomie komponentu, dzięki temu, jak Vue zarządza cyklem życia.
+
+## Przykład
+
+```vue fileName="src/components/Sidebar.vue"
+<script setup lang="ts">
+import { usePathname } from "vue-intlayer";
+
+const links = [
+  { href: "/dashboard", label: "Panel" },
+  { href: "/settings", label: "Ustawienia" },
+];
+
+const pathname = usePathname();
+</script>
+
+<template>
+  <nav>
+    <a
+      v-for="link in links"
+      :key="link.href"
+      :href="link.href"
+      :style="{ fontWeight: pathname === link.href ? 'bold' : 'normal' }"
+    >
+      {{ link.label }}
+    </a>
+  </nav>
+</template>
+```
+
+## Powiązane
+
+- [`useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/vue-intlayer/useLocale.md) — obecny locale + przełącznik locale
+- [`getPathWithoutLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/packages/intlayer/getPathWithoutLocale.md) — użyteczność bazowa (utility) wykorzystywana przez ten hook

package/docs/pl/plugins/sync-json.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-03-13
-updatedAt: 2025-12-13
+updatedAt: 2026-06-21
 title: Wtyczka Sync JSON
 description: Synchronizuj słowniki Intlayer z zewnętrznymi plikami JSON i18n (i18next, next-intl, react-intl, vue-i18n i inne). Zachowaj istniejące i18n, korzystając z Intlayer do zarządzania, tłumaczenia i testowania swoich komunikatów.
 keywords:
@@ -24,6 +24,9 @@ slugs:
   - sync-json
 youtubeVideo: https://www.youtube.com/watch?v=MpGMxniDHNg
 history:
+  - version: 9.0.0
+    date: 2026-06-21
+    changes: "Dodano opcję splitKeys (jeden słownik na klucz przestrzeni nazw najwyższego poziomu) dla układów jednoplikowych next-intl / react-intl"
   - version: 6.1.6
     date: 2025-10-05
     changes: "Pierwsza dokumentacja wtyczki Sync JSON"
@@ -59,9 +62,64 @@ pnpm add -D @intlayer/sync-json-plugin
 npm i -D @intlayer/sync-json-plugin
 ```
 
-## Szybki start
+## Plugins
 
-Dodaj wtyczkę do swojego pliku `intlayer.config.ts` i wskaż ją na istniejącą strukturę JSON.
+This package provides two plugins:
+
+- `loadJSON`: Load JSON files into Intlayer dictionaries.
+  - This plugin is used to load JSON files from a source and will be loaded into Intlayer dictionaries. It can scan all the codebase and search for specific JSON files.
+    This plugin can be used
+    - if you use an i18n library that impose a specific location for your JSON to be loaded (ex: `next-intl`, `i18next`, `react-intl`, `vue-i18n`, etc.), but you want to place your content declaration where you want in your code base.
+    - It can also be used if you want to fetch your messages from a remote source (ex: a CMS, a API, etc.) and store your messages in JSON files.
+
+  > Under the hood, this plugin will scan all the codebase and search for specific JSON files and load them into Intlayer dictionaries.
+  > Note that this plugin will not write the output and translations back to the JSON files.
+
+- `syncJSON`: Synchronize JSON files with Intlayer dictionaries.
+  - This plugin is used to synchronize JSON files with Intlayer dictionaries. It can scan the given location and load the JSON that match the pattern for specific JSON files. This plugin is useful if you want to get the benefits of Intlayer while using another i18n library.
+
+## Using both plugins
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON, syncJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  // Keep your current JSON files in sync with Intlayer dictionaries
+  plugins: [
+    /**
+     * Will load all the JSON files in the src that match the pattern {key}.i18n json
+     */
+    loadJSON({
+      source: ({ key }) => `./src/**/${key}.i18n.json`,
+      locale: Locales.ENGLISH,
+      priority: 1, // Ensures these JSON files take precedence over files at `./locales/en/${key}.json`
+      format: "intlayer", // Format of the JSON content
+    }),
+    /**
+     * Will load, and write the output and translations back to the JSON files in the locales directory
+     */
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      priority: 0,
+      format: "i18next",
+    }),
+  ],
+};
+
+export default config;
+```
+
+## `syncJSON` plugin
+
+### Quick start
+
+Add the plugin to your `intlayer.config.ts` and point it at your existing JSON structure.
 
 ```ts fileName="intlayer.config.ts"
 import { Locales, type IntlayerConfig } from "intlayer";
@@ -78,6 +136,7 @@ const config: IntlayerConfig = {
     syncJSON({
       // Układ per-locale, per-namespace (np. next-intl, i18next z przestrzeniami nazw)
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "icu",
     }),
   ],
 };
@@ -88,14 +147,27 @@ export default config;
 Alternatywa: pojedynczy plik na locale (częste w konfiguracjach i18next/react-intl):
 
 ```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ locale }) => `./locales/${locale}.json`,
-  }),
-];
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  plugins: [
+    syncJSON({
+      format: "i18next",
+      source: ({ locale }) => `./locales/${locale}.json`,
+      format: "i18next",
+    }),
+  ],
+};
+
+export default config;
 ```
 
-### Jak to działa
+#### How it works
 
 - Odczyt: wtyczka wykrywa pliki JSON zdefiniowane przez twój builder `source` i ładuje je jako słowniki Intlayer.
 - Zapis: po budowaniu i wypełnianiu, zapisuje zlokalizowane pliki JSON z powrotem pod te same ścieżki (z końcowym znakiem nowej linii, aby uniknąć problemów z formatowaniem).
@@ -109,6 +181,7 @@ syncJSON({
   location?: string, // opcjonalna etykieta, domyślnie: "plugin"
   priority?: number, // opcjonalny priorytet do rozstrzygania konfliktów, domyślnie: 0
   format?: 'intlayer' | 'icu' | 'i18next', // opcjonalny formatator, używany dla kompatybilności z runtime Intlayer
+  splitKeys?: boolean, // opcjonalnie, dzieli pojedynczy plik na jeden słownik na klucz przestrzeni nazw najwyższego poziomu (automatycznie wykrywane)
 });
 ```
 
@@ -133,11 +206,43 @@ syncJSON({
 }),
 ```
 
-## Wiele źródeł JSON i priorytet
+#### `splitKeys` (boolean)
+
+Kontroluje, czy pojedynczy plik JSON, którego **klucze pierwszego poziomu są przestrzeniami nazw**, powinien stać się jednym słownikiem na klucz najwyższego poziomu, zamiast pojedynczego słownika zawierającego cały plik.
+
+Odpowiada to modelowi przestrzeni nazw bibliotek takich jak `next-intl` i `react-intl`, gdzie jeden plik `messages/{locale}.json` grupuje kilka przestrzeni nazw według kluczy pierwszego poziomu, z których każda jest adresowana niezależnie (np. `useTranslations('Hero')` rozwiązuje się do słownika `Hero`).
+
+- `undefined` (domyślnie): **automatycznie wykrywane** — plik jest dzielony, gdy wzorzec `source` nie zawiera segmentu `{key}` (jeden plik zawiera każdą przestrzeń nazw), i zachowywany jako pojedynczy słownik w przeciwnym razie (jeden plik na klucz).
+- `true`: zawsze dzieli każdy klucz najwyższego poziomu na własny słownik.
+- `false`: nigdy nie dzieli; cały plik staje się pojedynczym słownikiem.
+
+Biorąc pod uwagę pojedynczy plik `messages/{locale}.json`:
+
+```json fileName="messages/en.json"
+{
+  "Hero": { "title": "Full-stack developer" },
+  "Nav": { "work": "Work", "about": "About" },
+  "About": { "lead": "I build apps end to end." }
+}
+```
+
+```ts fileName="intlayer.config.ts"
+syncJSON({
+  format: "icu",
+  source: ({ locale }) => `./messages/${locale}.json`,
+  // splitKeys: true, // domyślne, ponieważ wzorzec nie zawiera segmentu `{key}`
+}),
+```
+
+Tworzy to trzy słowniki — `Hero`, `Nav` i `About` — dzięki czemu `useTranslations('Hero')` (next-intl) rozwiązuje się poprawnie. Podczas zapisu zwrotnego wszystkie przestrzenie nazw są ponownie składane w ten sam plik dla danej lokalizacji.
 
-Możesz dodać wiele wtyczek `syncJSON`, aby synchronizować różne źródła JSON. Jest to przydatne, gdy masz wiele bibliotek i18n lub różne struktury JSON w swoim projekcie.
+> Kiedy zachowujesz jawny segment `{key}` w swoim `source` (np. `./locales/${locale}/${key}.json`), każdy plik jest już jedną przestrzenią nazw, więc dzielenie jest domyślnie wyłączone.
 
-### System priorytetów
+### Multiple JSON sources and priority
+
+You can add multiple `syncJSON` plugins to synchronize different JSON sources. This is useful when you have multiple i18n libraries or different JSON structures in your project.
+
+#### System priorytetów
 
 Gdy wiele wtyczek celuje w ten sam klucz słownika, parametr `priority` decyduje, która wtyczka ma pierwszeństwo:
 
@@ -186,73 +291,140 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-### Rozwiązywanie konfliktów
+## Load JSON plugin
 
-Gdy ten sam klucz tłumaczenia występuje w wielu źródłach JSON:
+### Quick start
 
-1. Wtyczka o najwyższym priorytecie decyduje o ostatecznej wartości
-2. Źródła o niższym priorytecie są używane jako zapasowe dla brakujących kluczy
-3. Pozwala to na utrzymanie tłumaczeń dziedziczonych podczas stopniowej migracji do nowych struktur
+Add the plugin to your `intlayer.config.ts` to ingest existing JSON files as Intlayer dictionaries. This plugin is read‑only (no writes to disk):
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON } from "@intlayer/sync-json-plugin";
 
-## Integracje
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
 
-Poniżej znajdują się typowe mapowania. Zachowaj swój runtime bez zmian; dodaj tylko wtyczkę.
+  plugins: [
+    // Ingest JSON messages located anywhere in your source tree
+    loadJSON({
+      source: ({ key }) => `./src/**/${key}.i18n.json`,
+      // Load a single locale per plugin instance (defaults to the config defaultLocale)
+      locale: Locales.ENGLISH,
+      priority: 0,
+    }),
+  ],
+};
 
-### i18next
+export default config;
+```
 
-Typowy układ plików: `./public/locales/{locale}/{namespace}.json` lub `./locales/{locale}/{namespace}.json`.
+Alternative: per‑locale layout, still read‑only (only the selected locale is loaded):
 
 ```ts fileName="intlayer.config.ts"
-import { syncJSON } from "@intlayer/sync-json-plugin";
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON } from "@intlayer/sync-json-plugin";
 
-export default {
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
   plugins: [
-    syncJSON({
-      format: "i18next",
+    loadJSON({
+      // Only files for Locales.FRENCH will be loaded from this pattern
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      locale: Locales.FRENCH,
     }),
   ],
 };
+
+export default config;
 ```
 
-### next-intl
+### How it works
 
-Wiadomości JSON na locale (często `./messages/{locale}.json`) lub na namespace.
+- Discover: builds a glob from your `source` builder and collects matching JSON files.
+- Ingest: loads each JSON file as an Intlayer dictionary with the provided `locale`.
+- Read‑only: does not write or format output files; use `syncJSON` if you need round‑trip sync.
+- Auto‑fill ready: defines a `fill` pattern so `intlayer content fill` can populate missing keys.
 
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ locale, key }) => `./messages/${locale}/${key}.json`,
-  }),
-];
+### API
+
+```ts
+loadJSON({
+  // Build paths to your JSON. `locale` is optional if your structure has no locale segment
+  source: ({ key, locale }) => string,
+
+  // Target locale for the dictionaries loaded by this plugin instance
+  // Defaults to configuration.internationalization.defaultLocale
+  locale?: Locale,
+
+  // Optional label to identify the source
+  location?: string, // default: "plugin"
+
+  // Priority used for conflict resolution against other sources
+  priority?: number, // default: 0
+
+  // Optional formatter for the JSON content
+  format?: 'intlayer' | 'icu' | 'i18next', // default: 'intlayer'
+
+  // Split a single file into one dictionary per top-level key (auto-detected)
+  splitKeys?: boolean,
+});
 ```
 
-Zobacz także: `docs/pl/intlayer_with_next-intl.md`.
+#### `format` ('intlayer' | 'icu' | 'i18next')
 
-### react-intl
+Specifies the formatter to use for the dictionary content when loading JSON files. This allows using different message formatting syntaxes compatible with various i18n libraries.
 
-Pojedynczy JSON na locale jest powszechny:
+- `'intlayer'`: The default Intlayer formatter (default).
+- `'icu'`: Uses ICU message formatting (compatible with libraries like react-intl, vue-i18n).
+- `'i18next'`: Uses i18next message formatting (compatible with i18next, next-i18next, Solid-i18next).
 
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ locale }) => `./locales/${locale}.json`,
-  }),
-];
+**Example:**
+
+```ts
+loadJSON({
+  source: ({ key }) => `./src/**/${key}.i18n.json`,
+  locale: Locales.ENGLISH,
+  format: "icu", // Use ICU formatting for compatibility
+}),
 ```
 
-### vue-i18n
+#### `splitKeys` (boolean)
 
-Może to być pojedynczy plik na locale lub na namespace:
+Takie samo zachowanie jak w [`syncJSON`](#splitkeys-boolean): gdy pojedynczy plik JSON grupuje kilka przestrzeni nazw według kluczy pierwszego poziomu, każdy klucz najwyższego poziomu staje się własnym słownikiem.
 
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ key, locale }) => `./src/locales/${locale}/${key}.json`,
-  }),
-];
+- `undefined` (domyślnie): **automatycznie wykrywane** — dzieli, gdy wzorzec `source` nie zawiera segmentu `{key}`, w przeciwnym razie pojedynczy słownik.
+- `true` / `false`: wymusza lub wyłącza dzielenie.
+
+```ts
+loadJSON({
+  source: ({ locale }) => `./messages/${locale}.json`,
+  format: "icu",
+  // splitKeys auto-enabled: `Hero`, `Nav`, `About`, … each become a dictionary
+}),
 ```
 
+### Behavior and conventions
+
+- If your `source` mask includes a locale placeholder, only files for the selected `locale` are ingested.
+- Jeśli w masce nie ma segmentu `{key}`, każdy klucz najwyższego poziomu pliku staje się domyślnie własnym słownikiem (zobacz [`splitKeys`](#splitkeys-boolean)). Ustaw `splitKeys: false`, aby zamiast tego załadować cały plik jako pojedynczy słownik indeksowy.
+- Keys are derived from file paths by substituting the `{key}` placeholder in your `source` builder.
+- The plugin only uses discovered files and does not fabricate missing locales or keys.
+- The `fill` path is inferred from your `source` and used to update missing values via CLI when you opt‑in.
+
+## Conflict resolution
+
+When the same translation key exists in multiple JSON sources:
+
+1. Wtyczka o najwyższym priorytecie decyduje o ostatecznej wartości
+2. Źródła o niższym priorytecie są używane jako zapasowe dla brakujących kluczy
+3. Pozwala to na utrzymanie tłumaczeń dziedziczonych podczas stopniowej migracji do nowych struktur
+
 ## CLI
 
 Synchronizowane pliki JSON będą traktowane jak inne pliki `.content`. Oznacza to, że wszystkie polecenia intlayer będą dostępne dla synchronizowanych plików JSON. W tym:

package/docs/pl/releases/v6.md

@@ -25,6 +25,10 @@ author: aymericzip
 
 Witamy w Intlayer v6! Ta wersja skupia się na wydajności, doświadczeniu deweloperskim oraz niezawodności. Poniżej znajdują się najważniejsze zmiany wraz z notatkami migracyjnymi i przykładami do kopiowania.
 
+## Spis treści
+
+<TOC levels={[2]} maxDepth={1} />
+
 ## Najważniejsze zmiany
 
 - Nowa komenda: `npx intlayer content test` do wykrywania brakujących tłumaczeń