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

package/docs/uk/packages/vite-intlayer/intlayerCompiler.md

@@ -0,0 +1,120 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: Документація плагина Vite intlayerCompiler | vite-intlayer
+description: Плагін Vite, який витягує вбудовані оголошення контенту Intlayer з файлів компонентів і записує їх у файли JSON словника під час збірки/трансформації.
+keywords:
+  - intlayerCompiler
+  - vite
+  - плагін
+  - компілятор
+  - контент
+  - словник
+  - інтернаціоналізація
+  - i18n
+slugs:
+  - doc
+  - packages
+  - vite-intlayer
+  - intlayerCompiler
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "Інтегровано в intlayer(); ініціалізація доки"
+author: aymericzip
+---
+
+# intlayerCompiler
+
+`intlayerCompiler` — це плагін Vite, який сканує вихідні файли компонентів на наявність **вбудованих оголошень контенту Intlayer** (inline declarations) — контенту, визначеного безпосередньо всередині компонента, а не в окремому файлі `.content.ts`, — і записує їх у файли JSON словника під час фази трансформації.
+
+> **Починаючи з Intlayer v9**, `intlayerCompiler` автоматично включається в основний плагін [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/vite-intlayer/intlayer.md), якщо в конфігурації Intlayer увімкнено компілятор (`compiler.enabled: true`) і вказано шлях виводу (`compiler.output`). Вам потрібно реєструвати його окремо лише в тому випадку, якщо ви хочете повністю контролювати конфігурацію компілятора.
+
+## Використання
+
+### У складі `intlayer()` (рекомендовано, v9+)
+
+Увімкніть компілятор у конфігурації Intlayer:
+
+```ts
+// intlayer.config.ts
+import { defineConfig } from "intlayer";
+
+export default defineConfig({
+  compiler: {
+    enabled: true,
+    output: "./src/dictionaries", // куди записуються витягнуті словники
+  },
+});
+```
+
+Потім використовуйте стандартний плагін без додаткової реєстрації:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+### Окремо (за необхідності)
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayerCompiler } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayerCompiler()],
+});
+```
+
+## Опції
+
+```ts
+import type { IntlayerCompilerOptions } from "vite-intlayer";
+```
+
+| Опція            | Тип                       | Опис                                                                                              |
+| ---------------- | ------------------------- | ------------------------------------------------------------------------------------------------- |
+| `configOptions`  | `GetConfigurationOptions` | Перевизначення конфігурації Intlayer, що передається в `getConfiguration()`.                      |
+| `compilerConfig` | `Partial<CompilerConfig>` | Перевизначення специфічних налаштувань компілятора (наприклад, `enabled`, `output`, `filesList`). |
+
+### Приклад
+
+```ts
+intlayerCompiler({
+  configOptions: { configFile: "./config/intlayer.config.ts" },
+  compilerConfig: { enabled: true, output: "./src/dictionaries" },
+});
+```
+
+## Як це працює
+
+### Фаза трансформації
+
+Для кожного вихідного файлу, що відповідає `compiler.filesList`, плагін компілятора:
+
+1. Пропускає вміст файлу через `extractContent` із `@intlayer/babel`.
+2. Викликає `onExtract` для кожного знайденого оголошення, записуючи результуючий JSON словника в `compiler.output`.
+3. Повертає трансформований вихідний код із вбудованими оголошеннями, заміненими стандартними викликами `useIntlayer('key')` / `getIntlayer('key')`.
+
+Підтримувані типи файлів: `.ts`, `.tsx`, `.js`, `.jsx`, `.vue`, `.svelte`, `.astro`.
+
+### HMR (Hot Module Replacement)
+
+Коли файл компонента зберігається в режимі розробки, компілятор:
+
+1. Виявляє зміну файлу через хук `handleHotUpdate` у Vite.
+2. Повторно витягує контент з оновленого файлу.
+3. Записує оновлений JSON словника.
+4. Запускає повне перезавантаження сторінки (`server.ws.send({ type: 'full-reload' })`).
+
+Затримка (debounce) у 500 мс запобігає нескінченному циклу повторного витягування, викликаному самим записом словника (який також запускає подію зміни файлу).
+
+### Дедуплікація
+
+`intlayerCompiler` використовує той самий механізм дедуплікації `createPrimaryInstanceGuard`, що й інші вбудовані плагіни. Коли присутні як `intlayer()` (який включає компілятор), так і ручний виклик `intlayerCompiler()`, запускається тільки перший зареєстрований екземпляр — словники не записуються двічі.

package/docs/uk/packages/vite-intlayer/intlayerMinify.md

@@ -0,0 +1,92 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: Документація плагина Vite intlayerMinify | vite-intlayer
+description: Плагін Vite, який мінімізує зкомпільовані файли JSON словника Intlayer та опціонально приховує імена полів вмісту для зменшення розміру бандлу.
+keywords:
+  - intlayerMinify
+  - vite
+  - плагін
+  - мінімізація
+  - розмір бандлу
+  - словник
+  - інтернаціоналізація
+  - i18n
+slugs:
+  - doc
+  - packages
+  - vite-intlayer
+  - intlayerMinify
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "Ініціалізація доки"
+author: aymericzip
+---
+
+# intlayerMinify
+
+`intlayerMinify` — це плагін Vite, який мінімізує зкомпільовані файли JSON словників під час збірки для продакшену. Він видаляє всі непотрібні пробіли і, у поєднанні з `intlayerPrune`, опціонально перейменовує поля вмісту на короткі буквені аліаси (`a`, `b`, `c`, …) для додаткового зменшення розміру бандлу.
+
+> Плагін вже автоматично включений та налаштований, якщо ви використовуєте [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/vite-intlayer/intlayer.md). Вам потрібно реєструвати його вручну тільки в тому випадку, если ви самостійно збираєте стек плагінів.
+
+## Використання
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayerMinify, intlayerPrune } from "vite-intlayer";
+import { createPruneContext } from "@intlayer/babel";
+
+const pruneContext = createPruneContext();
+
+export default defineConfig({
+  plugins: [
+    intlayerPrune(intlayerConfig, pruneContext),
+    intlayerMinify(intlayerConfig, pruneContext),
+  ],
+});
+```
+
+## Умови активації
+
+`intlayerMinify` активний **тільки** за виконання всіх трьох наступних умов:
+
+1. Команда Vite — `build` (не `serve` / dev).
+2. `build.optimize` має значення `true` (або `undefined`, що за замовчуванням дорівнює `true` для збірок).
+3. `build.minify` має значення `true` у вашій конфігурації Intlayer.
+
+Він автоматично **вимикається**, коли `editor.enabled` має значення `true`, оскільки редактору потрібен повний, зрозумілий людині вміст словників.
+
+## Що мінімізується
+
+Плагін обробляє два шляхи зберігання словників (що визначаються з `intlayer.system`):
+
+- `dictionariesDir` — статичні словники для всіх мов (наприклад, `.intlayer/dictionaries/*.json`)
+- `dynamicDictionariesDir` — динамічні словники для конкретних мов
+
+> Словники в режимі fetch (`fetchDictionariesDir`) **ніколи** не мінімізуються, оскільки вони завантажуються з віддаленого API під час виконання з використанням оригінальних імен полів. Перейменування полів призвело б до невідповідності між відповіддю сервера та зверненнями до властивостей на стороні клієнта.
+
+## Приховування імен полів (мінімізація властивостей)
+
+Коли `intlayerPrune` аналізує кодову базу і заповнює карту `pruneContext.dictionaryKeyToFieldRenameMap`, `intlayerMinify` також перейменовує імена полів контенту на короткі аліаси. Наприклад:
+
+```json
+// до
+{ "key": "myDict", "content": { "title": "Hello", "description": "World" } }
+
+// після (з приховуванням)
+{ "key": "myDict", "content": { "a": "Hello", "b": "World" } }
+```
+
+Відповідні звернення до властивостей у вихідних файлах перейменовуються на кроці Babel в `intlayerOptimize`, тому поведінка в рантаймі залишається незмінною.
+
+Внутрішні поля Intlayer (`nodeType`, `translation` тощо) ніколи не перейменовуються.
+
+## Граничні випадки (Edge-cases)
+
+Словники, позначені в `pruneContext.dictionariesWithEdgeCases` (структурні аномалії, виявлені під час фази очищення), повністю пропускаються — вони не мінімізуються і не приховуються, щоб уникнути відправки пошкоджених даних.
+
+## Кваліфіковані групи (колекції / варіанти / метадані)
+
+Для словників із масивом `qualifierTypes` (колекції, варіанти та метадані) плагін зберігає масив `qualifierTypes` та карту `meta` без змін. Маскуються лише імена полів усередині записів `content`. Композитні ключі (що використовуються для зіставлення селекторів під час виконання) ніколи не змінюються.

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

@@ -0,0 +1,172 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: Документація плагина Vite intlayerProxy | vite-intlayer
+description: Middleware локалізації роутингу для серверів dev/preview у Vite та серверного рендерингу (SSR) у продакшені. Обробляє визначення мови, перенаправлення URL та внутрішні перезаписи шляхів.
+keywords:
+  - intlayerProxy
+  - vite
+  - плагін
+  - middleware
+  - локаль
+  - роутинг
+  - інтернаціоналізація
+  - i18n
+  - SSR
+slugs:
+  - doc
+  - packages
+  - vite-intlayer
+  - intlayerProxy
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "Параметр configOptions об'єднано в один об'єкт налаштувань; проксі вбудовано в intlayer()"
+author: aymericzip
+---
+
+# intlayerProxy
+
+`intlayerProxy` — це плагін Vite, який реєструє проміжне програмне забезпечення (middleware) локалізації роутингу для **будь-якого середовища**: dev-сервера, preview-сервера та продакшен SSR (Nitro / TanStack Start).
+
+> **Починаючи з Intlayer v9**, `intlayerProxy` автоматично включається в основний плагін [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/vite-intlayer/intlayer.md) і активований за замовчуванням за допомогою налаштування `routing.enableProxy: true`. Вам потрібно реєструвати його окремо лише в тому випадку, якщо вам потрібен низькорівневий контроль або якщо ви використовуєте його за межами стандартної конфігурації `intlayer()`.
+
+## Використання
+
+### У складі `intlayer()` (рекомендовано, v9+)
+
+Передайте параметри `proxy` в основний плагін замість окремої реєстрації `intlayerProxy`:
+
+```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"),
+      },
+    }),
+  ],
+});
+```
+
+### Окремо (за необхідності)
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+## Параметри
+
+```ts
+import type { IntlayerProxyPluginOptions } from "vite-intlayer";
+```
+
+Усі параметри є необов'язковими і передаються у вигляді єдиного об'єкта:
+
+| Параметр        | Тип                                 | Опис                                                                                                                                                                                        |
+| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ignore`        | `(req: IncomingMessage) => boolean` | Предикат, який виключає запити з локалізації роутингу. Поверніть `true`, щоб пропустити запит (наприклад, для роутів API, health check-ів).                                                 |
+| `configOptions` | `GetConfigurationOptions`           | Перевизначення конфігурації Intlayer, що передаються в `getConfiguration()`. Використовуйте, коли вам потрібно, щоб проксі читав конкретний конфігураційний файл або перевизначав значення. |
+
+### Приклад
+
+```ts
+intlayerProxy({
+  ignore: (req) => req.url?.startsWith("/api"),
+  configOptions: { configFile: "./config/intlayer.config.ts" },
+});
+```
+
+## createIntlayerProxyHandler
+
+`createIntlayerProxyHandler` створює незалежний від фреймворку Node.js middleware `(req, res, next)`, який містить всю логіку локалізації роутингу. Це корисно в середовищах, де API плагінів Vite недоступний (наприклад, на звичайному сервері Node.js або в кастомному модулі 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);
+```
+
+### Продакшен SSR (TanStack Start / Nitro через 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"),
+  })
+);
+```
+
+## Поведінка роутингу
+
+Цей middleware дублює логіку роутингу з middleware `next-intlayer` і підтримує всі режими роутингу Intlayer.
+
+### Режими роутингу
+
+| Режим           | URL видно в браузері     | Поведінка                                                                                                                      |
+| --------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| `prefix`        | `/uk/about`              | За замовчуванням. Префікс мови в URL. Мова за замовчуванням перенаправляє на URL без префікса, якщо не активний `prefix-all`.  |
+| `prefix-all`    | `/en/about`, `/uk/about` | Усі мови (включаючи мову за замовчуванням) завжди мають префікс в URL.                                                         |
+| `no-prefix`     | `/about`                 | Немає мови в URL. Мова зберігається тільки в cookies; перезапис URL відбувається на внутрішньому рівні.                        |
+| `search-params` | `/about?locale=uk`       | Мова передається як query-параметр. Перенаправляє для додавання/оновлення параметра `locale`, якщо він відсутній або застарів. |
+
+### Пріоритет визначення
+
+1. Префікс шляху URL (наприклад, `/uk/about` → `uk`).
+2. Значення в cookie / localStorage (`intlayer-locale`).
+3. Заголовок `Accept-Language`.
+4. `defaultLocale` з конфігурації.
+
+### Автоматичний обхід (Bypass)
+
+Цей middleware завжди пропускає наступні запити безпосередньо без обробки локалі:
+
+- Запити, що відповідають предикату `ignore`.
+- `/node_modules/**`
+- `/@**` — внутрішні запити Vite (`@vite/`, `@fs/`, `@id/` тощо).
+- `/_**` — внутрішні запити сервера (`__vite_ping`, `__manifest` тощо).
+- Запити, шлях яких закінчується розширенням файлу (статичні файли). Якщо в шляху статичного файлу присутній мовний префікс (наприклад, `/uk/logo.png`), він видаляється, щоб файл міг бути відданий коректно.
+
+### Роутинг по доменах
+
+Коли у вашій конфігурації Intlayer налаштовано параметр `routing.domains`, цей middleware обробляє роутинг мов між різними доменами:
+
+- Запит для `/zh/about` на домені `intlayer.org` перенаправляється на `https://intlayer.zh/about`, коли `domains.zh = "intlayer.zh"`.
+- Запит до `intlayer.zh/about` внутрішньо переписується в `/zh/about`, щоб заповнився параметр маршруту `[locale]`.
+
+### Захист від нескінченного редиректу
+
+Цей middleware відстежує кількість перенаправлень для пари `originalUrl → newUrl` у рухомому 2-секундному вікні. Більше 10 перенаправлень у цьому вікні повертають помилку `500` із докладним описом замість нескінченного циклу.
+
+## Nitro / SSR у продакшені (автоматичне впровадження, v9+)
+
+Коли `intlayerProxy` використовується як плагін Vite, він містить властивість `.nitro`. Плагін збірки `nitro/vite` зчитує цю властивість і поміщає її в `nitroConfig.modules`, завдяки чому `intlayerNitroHandler` реєструється як middleware сервера Nitro автоматично — для продакшен SSR не потрібне ручне налаштування.
+
+Обробник Nitro використовує модель подій Web Fetch API h3 v2 (а не `fromNodeMiddleware`), тому він сумісний з усіма пресетами Nitro: Node, Bun, Deno, edge runtimes.
+
+## Застарілі аліаси
+
+| Застарілий експорт         | Заміна          |
+| -------------------------- | --------------- |
+| `intlayerMiddleware`       | `intlayerProxy` |
+| `intLayerMiddlewarePlugin` | `intlayerProxy` |

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

@@ -14,6 +14,9 @@ slugs:
   - vue-intlayer
   - exports
 history:
+  - version: 10.0.0
+    date: 2026-06-23
+    changes: "Додано утиліту usePathname"
   - version: 8.0.0
     date: 2026-01-21
     changes: "Уніфікована документація для всіх експортів"
@@ -59,6 +62,7 @@ import "vue-intlayer";
 | `useDictionaryAsync`   | Те саме, що `useDictionary`, але обробляє асинхронні словники.                                                                          | -                                                                                                                     |
 | `useDictionaryDynamic` | Те саме, що `useDictionary`, але обробляє динамічні словники.                                                                           | -                                                                                                                     |
 | `useLocale`            | Повертає поточну локаль та функцію для її встановлення.                                                                                 | -                                                                                                                     |
+| `usePathname`          | Повертає поточний pathname як `ComputedRef<string>` з видаленим сегментом локалі. Реактивний до подій `popstate`.                       | [usePathname](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/vue-intlayer/usePathname.md)     |
 | `useRewriteURL`        | Composable на стороні клієнта для керування переписуванням URL. Автоматично оновлює URL, якщо існує локалізоване правило переписування. | [useRewriteURL](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/vue-intlayer/useRewriteURL.md) |
 | `useIntl`              | Повертає об'єкт Intl для поточної локалі.                                                                                               | -                                                                                                                     |
 | `useLoadDynamic`       | Composable для завантаження динамічних словників.                                                                                       | -                                                                                                                     |

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

@@ -0,0 +1,109 @@
+---
+createdAt: 2026-06-22
+updatedAt: 2026-06-22
+title: Документація функції usePathname | vue-intlayer
+description: Дізнайтеся, як використовувати функцію usePathname з пакета vue-intlayer
+keywords:
+  - usePathname
+  - pathname
+  - locale
+  - Intlayer
+  - Інтернаціоналізація
+  - Документація
+  - Vue
+  - JavaScript
+slugs:
+  - doc
+  - packages
+  - vue-intlayer
+  - usePathname
+history:
+  - version: 10.0.0
+    date: 2026-06-23
+    changes: "Додано утиліту usePathname"
+  - version: 8.2.0
+    date: 2026-06-22
+    changes: "Ініціалізація історії"
+author: aymericzip
+---
+
+# Інтеграція з Vue: Документація `usePathname`
+
+Функція `usePathname` повертає поточний шлях браузера (pathname) з видаленим сегментом локалі, як Vue `ComputedRef<string>`. Це корисно для створення навігації, що залежить від локалі — наприклад, щоб визначити, який елемент навігації є активним — без необхідності обробляти префікс локалі вручну.
+
+## Імпорт `usePathname` у Vue
+
+```typescript
+import { usePathname } from "vue-intlayer";
+```
+
+## Огляд
+
+`usePathname` створює Vue обчислюване посилання (computed ref), яке зчитує `window.location.pathname`, видаляє префікс локалі через `getPathWithoutLocale` і оновлює своє значення щоразу, коли браузер ініціює подію `popstate` (навігація назад/вперед). Це значення можна безпосередньо використовувати у ваших шаблонах Vue або функціях setup.
+
+## Використання
+
+```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>
+```
+
+## Значення, що повертається
+
+| Тип                   | Опис                                                                                |
+| --------------------- | ----------------------------------------------------------------------------------- |
+| `ComputedRef<string>` | Vue Computed Ref, що містить поточний шлях браузера (pathname) без префіксу локалі. |
+
+## Поведінка
+
+- **Видалення локалі (Locale stripping)**: Видаляє початковий сегмент локалі (наприклад, `/uk/dashboard` → `/dashboard`).
+- **Реактивність**: Оновлює значення при кожній події `popstate` (навігація браузера назад / вперед).
+- **Безпека для SSR**: Повертає `""`, коли `window` недоступний.
+- **Очищення (Cleanup)**: Слухач події `popstate` додається глобально під час ініціалізації і зазвичай не потребує ручного очищення в кожному компоненті завдяки тому, як Vue керує життєвим циклом.
+
+## Приклад
+
+```vue fileName="src/components/Sidebar.vue"
+<script setup lang="ts">
+import { usePathname } from "vue-intlayer";
+
+const links = [
+  { href: "/dashboard", label: "Дашборд" },
+  { href: "/settings", label: "Налаштування" },
+];
+
+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>
+```
+
+## Пов'язане
+
+- [`useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/vue-intlayer/useLocale.md) — поточна локаль + перемикач локалі
+- [`getPathWithoutLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/packages/intlayer/getPathWithoutLocale.md) — базова утиліта, що використовується цим хуком

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

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-03-13
-updatedAt: 2025-12-13
+updatedAt: 2026-06-21
 title: Плагін Sync JSON
 description: Синхронізуйте словники Intlayer із зовнішніми i18n JSON-файлами (i18next, next-intl, react-intl, vue-i18n та ін.). Залишайте ваш існуючий i18n-стек і використовуйте Intlayer для керування, перекладу та тестування повідомлень.
 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: "Додано опцію splitKeys (один словник на ключ простору імен верхнього рівня) для макетів next-intl / react-intl з одним файлом"
   - version: 7.5.0
     date: 2025-12-13
     changes: "Додано підтримку форматів ICU та i18next"
@@ -105,7 +108,6 @@ const config: IntlayerConfig = {
      * Завантажить та запише результати й переклади назад у JSON-файли в директорії locales
      */
     syncJSON({
-      format: "i18next",
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
       priority: 0,
       format: "i18next",
@@ -182,6 +184,7 @@ syncJSON({
   location?: string, // необов'язковий ярлик, за замовчуванням: "plugin"
   priority?: number, // необов'язковий пріоритет для вирішення конфліктів, за замовчуванням: 0
   format?: 'intlayer' | 'icu' | 'i18next', // необов'язковий форматтер, використовується для сумісності з intlayer runtime
+  splitKeys?: boolean, // необов'язково, розділяє один файл на один словник для кожного ключа простору імен верхнього рівня (автоматично визначається)
 });
 ```
 
@@ -205,6 +208,38 @@ syncJSON({
 }),
 ```
 
+#### `splitKeys` (boolean)
+
+Контролює, чи повинен один JSON-файл, **ключі першого рівня якого є просторами імен**, стати одним словником на ключ верхнього рівня, замість одного словника, що містить весь файл.
+
+Це відповідає моделі просторів імен таких бібліотек, як `next-intl` та `react-intl`, де один файл `messages/{locale}.json` групує кілька просторів імен за ключами першого рівня, кожен з яких адресується незалежно (наприклад, `useTranslations('Hero')` розв'язується до словника `Hero`).
+
+- `undefined` (за замовчуванням): **автоматично визначається** — файл розділяється, коли шаблон `source` не має сегмента `{key}` (один файл містить кожен простір імен), і залишається як єдиний словник в іншому випадку (один файл на ключ).
+- `true`: завжди розділяти кожен ключ верхнього рівня на окремий словник.
+- `false`: ніколи не розділяти; весь файл стає єдиним словником.
+
+Дано один файл `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, // мається на увазі, оскільки шаблон не має сегмента `{key}`
+}),
+```
+
+Це створює три словники — `Hero`, `Nav` та `About` — тому `useTranslations('Hero')` (next-intl) розв'язується коректно. При зворотному записі всі простори імен знову збираються в той самий файл для кожної локалі.
+
+> Коли ви зберігаєте явний сегмент `{key}` у вашому `source` (наприклад, `./locales/${locale}/${key}.json`), кожен файл вже є одним простором імен, тому розділення за замовчуванням вимкнено.
+
 ### Кілька джерел JSON та пріоритет
 
 Ви можете додавати кілька плагінів `syncJSON` для синхронізації різних джерел JSON. Це корисно, коли у вашому проєкті використовується декілька i18n бібліотек або різні структури JSON.
@@ -337,6 +372,9 @@ loadJSON({
 
   // Необов'язковий форматувач для JSON-вмісту
   format?: 'intlayer' | 'icu' | 'i18next', // за замовчуванням: 'intlayer'
+
+  // Розділяє один файл на один словник для кожного ключа верхнього рівня (автоматично визначається)
+  splitKeys?: boolean,
 });
 ```
 
@@ -358,10 +396,25 @@ loadJSON({
 }),
 ```
 
+#### `splitKeys` (boolean)
+
+Така ж поведінка, як і в [`syncJSON`](#splitkeys-boolean): коли один JSON-файл групує кілька просторів імен за ключами першого рівня, кожен ключ верхнього рівня стає окремим словником.
+
+- `undefined` (за замовчуванням): **автоматично визначається** — розділяється, коли шаблон `source` не має сегмента `{key}`, інакше — єдиний словник.
+- `true` / `false`: примусово ввімкнути або вимкнути розділення.
+
+```ts
+loadJSON({
+  source: ({ locale }) => `./messages/${locale}.json`,
+  format: "icu",
+  // splitKeys auto-enabled: `Hero`, `Nav`, `About`, … each become a dictionary
+}),
+```
+
 ### Поведінка та конвенції
 
 - Якщо ваша маска `source` містить плейсхолдер локалі, імпортуються лише файли для обраної `locale`.
-- Якщо в масці немає сегмента `{key}`, ключ словника, "index".
+- Якщо в масці немає сегмента `{key}`, кожен ключ верхнього рівня файлу за замовчуванням стає окремим словником (див. [`splitKeys`](#splitkeys-boolean)). Встановіть `splitKeys: false`, щоб замість цього завантажити весь файл як єдиний словник `index`.
 - Ключі виводяться зі шляхів файлів шляхом підстановки плейсхолдера `{key}` у вашому source builder.
 - Плагін використовує лише виявлені файли і не створює відсутні локалі чи ключі.
 - Шлях `fill` виводиться з вашого `source` і використовується для оновлення відсутніх значень через CLI, якщо ви погодитесь.

package/docs/uk/releases/v6.md

@@ -25,6 +25,10 @@ author: aymericzip
 
 Ласкаво просимо в Intlayer v6! У цьому релізі акцент зроблено на продуктивності, developer experience та надійності. Нижче наведено основні моменти, нотатки щодо міграції та приклади, які можна копіювати й вставляти.
 
+## Зміст
+
+<TOC levels={[2]} maxDepth={1} />
+
 ## Основні зміни
 
 - Нова команда: `npx intlayer content test` для виявлення відсутніх перекладів

package/docs/uk/releases/v7.md

@@ -25,6 +25,10 @@ author: aymericzip
 
 Ласкаво просимо до Intlayer v7! Це велике оновлення вводить суттєві покращення продуктивності, type safety і developer experience. Нижче наведено основні зміни, нотатки щодо міграції та практичні приклади.
 
+## Зміст
+
+<TOC levels={[2]} maxDepth={1} />
+
 ## Основні моменти
 
 - Підтримка Next.js 16