@intlayer/docs 9.1.3 → 9.3.0

package/docs/uk/analytics.md

@@ -0,0 +1,222 @@
+---
+createdAt: 2026-07-08
+updatedAt: 2026-07-08
+title: Intlayer Analytics | Відстеження показів контенту та проведення A/B-тестування
+description: Дізнайтеся, як @intlayer/analytics відстежує перегляди сторінок/локалей та покази контенту, і як використовувати це для проведення A/B-тестування вашого контенту в Intlayer.
+keywords:
+  - Аналітика (Analytics)
+  - A/B Тестування
+  - Аудиторія (Audience)
+  - Інтернаціоналізація
+  - Документація
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - analytics
+history:
+  - version: 9.0.0
+    date: 2026-07-08
+    changes: "Init doc — пакет @intlayer/analytics, відстеження на рівні провайдера/вузла, A/B-тестування, дашборд"
+author: aymericzip
+---
+
+# Документація Intlayer Analytics
+
+`@intlayer/analytics` — це додатковий пакет, який показує, **який контент насправді бачать** ваші відвідувачі (яку сторінку, в якій локалі та який саме фрагмент перекладеного контенту), щоб ви могли розуміти свою аудиторію та **проводити A/B-тестування контенту**.
+
+## Зміст
+
+<TOC/>
+
+---
+
+## Що відстежується
+
+`@intlayer/analytics` об'єднує в пакети (batch) три типи анонімних подій:
+
+| Подія              | Де фіксується                             | Про що вона говорить                                                                                                                            |
+| ------------------ | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `page_view`        | На рівні провайдера (`IntlayerProvider`)  | Яку сторінку та локаль переглянув користувач (сесія) під час першого завантаження, зміни маршруту або зміни локалі.                             |
+| `content_exposure` | На рівні вузла (`useIntlayer` / плагіни)  | Який ключ словника / шлях до ключа було фактично вирішено (resolved) та показано — і, якщо це частина експерименту, який **варіант** (variant). |
+| `conversion`       | Скрізь, де викликається `useConversion()` | Досягнення мети (реєстрація, клік, покупка...), пов'язане з A/B-варіантом, який бачив користувач у цій сесії.                                   |
+
+Події збираються в пам'яті та надсилаються як **один пакетний запит приблизно кожні 20 секунд** — а не при кожному натисканні клавіші або рендерингу — тому аналітика ніколи не впливає на час першого рендерингу і не додає запити на кожну взаємодію.
+
+## Як це працює для A/B-тестування контенту
+
+Intlayer вже дозволяє вам оголошувати [Варіанти (Variants)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dynamic_dictionaries/index.md) контенту (наприклад, словник `hero-banner` з варіантами `control` та `black_friday`). `@intlayer/analytics` замикає цикл:
+
+1. `getVariant(experimentKey, variants)` детерміновано призначає кожну анонімну сесію варіанту — це чиста функція від ID сесії та ключа експерименту, тому призначення є **стабільним протягом усієї сесії** і не вимагає **запитів до сервера (server round-trips)** до першого рендерингу (без мерехтіння і зсувів макета).
+2. Кожна подія `content_exposure` містить показаний `variant`.
+3. `useConversion()` дозволяє пов'язати мету (наприклад, `"cta_click"`) з цим варіантом.
+4. Ендпоінт результатів експериментів у дашборді порівнює коефіцієнти конверсії (conversion rates) за варіантами, включаючи статистичну значущість (z-тест).
+
+## Встановлення
+
+`@intlayer/analytics` — це **однорангова (peer), необов'язкова** залежність. Вона ніколи автоматично не встановлюється фреймворками. Додайте її разом з `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
+```
+
+Якщо ви її не встановите, всі точки інтеграції будуть розв'язуватися у порожні операції (no-op) — див. [Нульові витрати, якщо не встановлено](#нульові-витрати-якщо-не-встановлено) нижче.
+
+## Налаштування
+
+Аналітика **повторно використовує існуючий блок конфігурації `editor`** — вам не потрібно заповнювати окрему схему конфігурації для `analytics`:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  editor: {
+    backendURL: "https://back.intlayer.org", // Також використовується як кінцева точка для збору аналітики
+    clientId: "your-client-id", // Також використовується як ключ проекту аналітики
+    clientSecret: "your-client-secret",
+  },
+};
+
+export default config;
+```
+
+- `editor.backendURL` — базовий URL, на який надсилаються події аналітики (`POST {backendURL}/api/analytics/events`).
+- `editor.clientId` — публічний ключ проекту, що присвоюється кожній прийнятій події. Він також діє як **перемикач увімкнення**: аналітика залишається повністю вимкненою (і видаляється при tree-shaking, див. нижче), доки не налаштовано `clientId`.
+
+Якщо ви самостійно розміщуєте (self-host) Intlayer, аналітика автоматично вказує на ваш власний екземпляр, оскільки вона використовує спільний `editor.backendURL`.
+
+## Підтримка фреймворків
+
+Аналітика вбудована у спільний `IntlayerProvider` з `react-intlayer`, тому вона доступна вже сьогодні скрізь, де використовується цей провайдер:
+
+| Фреймворк                                                | Статус                                                                                                     |
+| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| React                                                    | ✅ Доступно                                                                                                |
+| Next.js (`next-intlayer`)                                | ✅ Доступно (через `react-intlayer`)                                                                       |
+| React Native / Expo (`react-native-intlayer`)            | ✅ Доступно (через `react-intlayer`)                                                                       |
+| Vue, Svelte, Angular, Solid, Preact, Lit, Astro, Vanilla | 🚧 Заплановано — той самий клієнт, прив'язки на рівні провайдера за зразком розгортання `@intlayer/editor` |
+
+## Використання
+
+### Автоматичне відстеження на рівні провайдера
+
+Жодних змін у коді не потрібно. Як тільки встановлено `@intlayer/analytics` та налаштовано `editor.clientId`, `IntlayerProvider` автоматично:
+
+- ініціалізує клієнт аналітики при монтуванні (mount),
+- записує `page_view` при початковому завантаженні,
+- записує `page_view` при кожній зміні локалі,
+- запускає цикл очищення (flush) з інтервалом ~20 с і надсилає всі події, що залишилися, при розмонтуванні / закритті вкладки (через `navigator.sendBeacon`, з відкатом (fallback) на `fetch(..., { keepalive: true })`).
+
+### Автоматичне відстеження на рівні вузла
+
+Щоразу, коли `useIntlayer` розв'язує фрагмент контенту для відображення, інтерпретатор повідомляє про подію `content_exposure` для цього точного `dictionaryKey` + шляху до ключа + локалі — знову ж таки, жодних змін у коді не потрібно. Повторні покази одного й того ж вузла в межах вікна очищення (flush window) об'єднуються в одну подію з лічильником (`count`), тому список, що перемальовується (re-render) 50 разів, не надсилає 50 подій.
+
+### Відстеження конверсій для A/B-тестування
+
+Використовуйте `useConversion()`, щоб пов'язати мету з варіантом, який бачила сесія:
+
+```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",
+        })
+      }
+    >
+      Почати
+    </button>
+  );
+};
+```
+
+### Розв'язання варіанту на стороні клієнта
+
+```tsx fileName="useHeroVariant.ts" codeFormat="tsx"
+import { getGlobalAnalyticsClient } from "@intlayer/analytics/client";
+
+const client = getGlobalAnalyticsClient();
+const variant = client?.getVariant("homepage-hero", [
+  "control",
+  "black_friday",
+]);
+```
+
+## Конфіденційність та продуктивність
+
+- **Анонімність за дизайном**: сесії ідентифікуються за id, що обертається (rotating id); сервер (backend) коли-небудь зберігає лише **SHA-256 хеш** цього id — ніколи сам id і ніколи IP-адресу.
+- **Приблизне місцезнаходження (Coarse location)**: лише код країни, отриманий із заголовків геолокації CDN (наприклад, `cf-ipcountry`, `x-vercel-ip-country`, ...) — IP не зчитується і не зберігається.
+- **URL виключають параметри пошуку** за замовчуванням, тому рядки запиту (query strings) ніколи не фіксуються.
+- **Семпліювання (Sampling)**: `sampleRate` дозволяє зберігати лише частину подій показу контенту в додатках з високим трафіком.
+- **Пакетна передача (Batched)**: один запит приблизно кожні 20 секунд (`flushInterval`) або раніше, якщо буфер заповнений (`maxBufferSize`) — ніколи не надсилається один запит на кожну подію.
+
+### Нульові витрати, якщо не встановлено
+
+`@intlayer/analytics` дотримується того ж патерну опціональних залежностей, що й `@intlayer/editor`:
+
+- кожна точка інтеграції завантажує пакет через **динамічний `import()`, обгорнутий у `try/catch`** — додаток, який ніколи не встановлює `@intlayer/analytics`, не збільшує розмір збірки (bundle size) і не витрачає ресурси під час виконання, а також ніколи не бачить помилок;
+- змінна середовища часу компіляції (`INTLAYER_ANALYTICS_ENABLED`), що автоматично встановлюється в `'false'` пакетом `@intlayer/config`, коли не налаштовано `editor.clientId`, дозволяє бандлерам **видаляти весь код інтеграції (dead-code-eliminate)**;
+- аналітика вимкнена всередині iframe попереднього перегляду редактора/CMS Intlayer, тому сесії в редакторі ніколи не враховуються як реальний трафік.
+
+## Дашборд: Сторінка Analytics
+
+Як тільки ваш проект збере події, сторінка **Analytics** у [дашборді Intlayer](https://app.intlayer.org/analytics) (видна в бічній панелі після вибору проекту) покаже:
+
+- **Активні користувачі** — унікальні відвідувачі за вибране ковзне вікно (7 / 30 / 90 днів).
+- **Користувачі сьогодні** та **користувачі за останні 7 днів**.
+- **Перегляди сторінок (Page views)** за вибране вікно.
+- **Графік динаміки** унікальних відвідувачів по днях.
+- Вкладки з розбивкою по **Локалях (Locales)** та **Місцезнаходженню (Location)**, що ранжують вашу аудиторію за локаллю та країною.
+
+## Довідник API бекенда (Backend API reference)
+
+Всі ендпоінти для читання вимагають автентифікації; прийом даних публічний і асоціюється за `clientId` у тілі запиту.
+
+| Метод  | Ендпоінт                                    | Опис                                                                                |
+| ------ | ------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `POST` | `/api/analytics/events`                     | Прийом пакету подій (публічний, асоціюється за `clientId` в тілі).                  |
+| `GET`  | `/api/analytics/overview`                   | Загальні показники сторінок/локалей для автентифікованого проекту.                  |
+| `GET`  | `/api/analytics/audience?days=30`           | Унікальні відвідувачі, перегляди сторінок, серії по днях, розбивка (локаль+країна). |
+| `GET`  | `/api/analytics/content-stats`              | Загальні покази контенту, згруповані за ключем словника / шляхом / локаллю.         |
+| `GET`  | `/api/analytics/experiments/:experimentKey` | Коефіцієнти конверсії за варіантами та статистична значущість для A/B-тесту.        |
+
+Ви також можете викликати їх програмно за допомогою [CMS SDK](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/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);
+```
+
+## Корисні посилання
+
+- [Динамічні словники - Колекції та варіанти](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dynamic_dictionaries/index.md)
+- [Intlayer CMS - CMS SDK](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_CMS.md)
+- [Візуальний редактор Intlayer (Visual Editor)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_visual_editor.md)
+- [Довідник з конфігурації (Configuration Reference)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/configuration.md)
+- [Посібник із самостійного хостингу (Self-Hosting)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/self_hosting.md)

package/docs/uk/bundle_optimization.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-11-25
-updatedAt: 2026-06-07
+updatedAt: 2026-08-09
 title: Оптимізація розміру бандлу та продуктивності i18n
 description: Зменште розмір бандлу вашого застосунку завдяки оптимізації контенту інтернаціоналізації (i18n). Дізнайтеся, як використовувати tree shaking та ліниве завантаження (lazy loading) для словників за допомогою Intlayer.
 keywords:
@@ -16,6 +16,12 @@ slugs:
   - concept
   - bundle-optimization
 history:
+  - version: 9.2.1
+    date: 2026-08-09
+    changes: "`purge` та `minify` тепер працюють у Next.js через `@intlayer/swc` — файл `babel.config.js` не потрібен"
+  - version: 8.12.0
+    date: 2026-06-24
+    changes: "Перелік плагінів Babel у потрібному порядку конвеєра (extract → purge → minify → optimize) у довідкових таблицях"
   - version: 8.12.0
     date: 2026-06-07
     changes: "Додано `intlayerPurgeBabelPlugin` та `intlayerMinifyBabelPlugin` для Babel/Webpack; уточнено порядок конвеєра плагінів"
@@ -191,12 +197,14 @@ Intlayer використовує **підхід на рівні компоне
 
 Ці плагіни використовуються безпосередньо в `babel.config.js` для налаштувань на базі Webpack (Next.js із Babel, CRA, кастомний Webpack тощо).
 
+Таблиця нижче перелічує їх у потрібному порядку конвеєра (у тому самому порядку, в якому вони мають бути в `babel.config.js`):
+
 | Плагін                        | Що він робить                                                                                                                      |
 | :---------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- |
 | `intlayerExtractBabelPlugin`  | Сканує файли `.content.ts` та записує зібрані словники до папки `.intlayer/`                                                       |
-| `intlayerOptimizeBabelPlugin` | Переписує `useIntlayer('key')` на `useDictionary(hash)` та інжектить (вставляє) відповідний `import` словника                      |
 | `intlayerPurgeBabelPlugin`    | Сканує всі файли з кодом та видаляє **невикористані поля контенту** зі скомпільованих словників `.intlayer/**/*.json`              |
 | `intlayerMinifyBabelPlugin`   | **Перейменовує ключі полів контенту** на короткі алфавітні псевдоніми (наприклад, `title` → `a`) у JSON-файлах та у вихідному коді |
+| `intlayerOptimizeBabelPlugin` | Переписує `useIntlayer('key')` на `useDictionary(hash)` та інжектить (вставляє) відповідний `import` словника                      |
 
 > **Порядок плагінів має значення.** У файлі `babel.config.js` плагіни `purge` та `minify` мають з'являтися **перед** плагіном `optimize`. Оскільки `optimize` замінює `useIntlayer('key')` на непрозорий (opaque) виклик `useDictionary(hash)`, він стирає інформацію про ключ словника. Але саме ця інформація потрібна на етапах `purge` та `minify`, щоб розпізнати, які поля контенту використовуються.
 
@@ -205,9 +213,9 @@ Intlayer використовує **підхід на рівні компоне
 | Options helper               | З яким плагіном використовується |
 | :--------------------------- | :------------------------------- |
 | `getExtractPluginOptions()`  | `intlayerExtractBabelPlugin`     |
-| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin`    |
 | `getPurgePluginOptions()`    | `intlayerPurgeBabelPlugin`       |
 | `getMinifyPluginOptions()`   | `intlayerMinifyBabelPlugin`      |
+| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin`    |
 
 ### Плагіни Vite (`vite-intlayer`)
 
@@ -220,6 +228,20 @@ Intlayer використовує **підхід на рівні компоне
 | Dictionary minify      | Аналогічно до етапу запису JSON плагіна `intlayerMinifyBabelPlugin`                                                |
 | Babel transform        | Аналогічно до перейменування у вихідному коді плагіном `intlayerMinifyBabelPlugin` + `intlayerOptimizeBabelPlugin` |
 
+### Плагін SWC (`@intlayer/swc`)
+
+Користувачі Next.js **також ніколи не налаштовують це напряму**. Починаючи з **v9.2.1**, `withIntlayer()` у `next.config.ts` виконує весь конвеєр — purge, мініфікацію та переписування імпортів — спираючись лише на прапорці `build.purge` і `build.minify`.
+
+Роботу поділено на дві частини, бо Wasm-плагін SWC перетворює по одному файлу за раз і не має доступу до файлової системи:
+
+| Прохід                                                | Де виконується                   | Що робить                                                                                            |
+| :---------------------------------------------------- | :------------------------------- | :--------------------------------------------------------------------------------------------------- |
+| Аналіз використання + purge/мініфікація JSON          | Node, усередині `withIntlayer()` | Читає кожен вихідний файл компонента, переписує `.intlayer/**/*.json`, формує таблиці перейменування |
+| Переписування вихідного коду (`content.title` → `.a`) | `@intlayer/swc` (Wasm)           | Застосовує таблиці перейменування до відповідних звернень до властивостей у вашому коді              |
+| Переписування імпортів (`useIntlayer` → dict)         | `@intlayer/swc` (Wasm)           | Те саме, що `intlayerOptimizeBabelPlugin`                                                            |
+
+Визначення того, _які_ поля не використовуються і _який_ псевдонім отримає кожне з них, потребує стану між файлами та файлового вводу-виводу, тож ця половина виконується в Node; плагін SWC отримує лише готові таблиці.
+
 ## Налаштування за платформами
 
 <Tabs>
@@ -227,10 +249,12 @@ Intlayer використовує **підхід на рівні компоне
 
 ### Next.js
 
-Next.js потребує плагіна `@intlayer/swc` для етапу оптимізації (перезапису імпорту), оскільки Next.js використовує SWC для збірки.
+Next.js потребує плагіна `@intlayer/swc`, оскільки Next.js використовує SWC для збірок. Починаючи з **v9.2.1** цей єдиний пакет охоплює весь конвеєр — оптимізацію (переписування імпортів), purge та мініфікацію.
 
 > Цей плагін не встановлюється автоматично, адже плагіни SWC для Next.js ще мають експериментальний статус. У майбутньому це може змінитися.
 
+> **Next.js 16.1.0 — мінімальна версія.** Це перший реліз, побудований на прямо сумісному ABI Wasm-плагінів SWC; більш ранні релізи відхиляють плагін. `withIntlayer` зчитує вашу версію Next.js і просто не реєструє плагін нижче 16.1.0 — такі збірки все одно проходять успішно, просто без оптимізації бандла.
+
 <Tabs>
  <Tab value="npm">
 
@@ -265,33 +289,40 @@ intlayer-swc-plugin = "*"
 
 Після встановлення Intlayer автоматично виявить і почне використовувати цей плагін.
 
-Для етапів **purge та minify** (видалення та перейменування полів) вам треба встановити поруч `@intlayer/babel` і додати Babel-плагіни. Оскільки Next.js хоча й застосовує SWC для трансформацій, але продовжує зчитувати `babel.config.js` під час збирання налаштувань плагінів, Babel-плагіни запускатимуться як пре-пас (попередня обробка) перед SWC.
+Проходи **purge та мініфікації** (видалення й перейменування полів) не потребують ані додаткового пакета, ані `babel.config.js`. Оберніть свою конфігурацію в `withIntlayer` і увімкніть прапорці в `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 = {/* ваша конфігурація */};
+
+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: видалити невикористані поля контенту з .intlayer/**/*.json
-    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],
-    // Minify: перейменувати ключі полів контенту в JSON-файлах та вихідному коді
-    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],
-    // Примітка: intlayerOptimizeBabelPlugin тут НЕ потрібен, тому що
-    // @intlayer/swc вже відповідає за переписування useIntlayer → useDictionary.
-  ],
+const config: IntlayerConfig = {
+  build: {
+    purge: true, // видаляє невикористані поля контенту зі зібраного JSON
+    minify: true, // перейменовує ключі полів контенту на короткі псевдоніми
+  },
 };
+
+export default config;
 ```
 
+Під час `next build` `withIntlayer` аналізує ваші джерела, переписує скомпільовані словники та передає отримані таблиці перейменування полів до `@intlayer/swc`, який оновлює відповідні звернення до властивостей у вашому коді.
+
+> Використовуйте асинхронний `withIntlayer`, а не `withIntlayerSync`. Синхронний варіант не запускає конвеєр аналізу, тож purge і мініфікація з ним не діють.
+
+> Purge і мініфікація виконуються лише під час `next build` — конвеєр оптимізації вимкнено під час `next dev`.
+
+> Вони також вимикаються, коли налаштовано викликачів з адаптерів сумісності (`swcExtraCallers`, які задають пакети сумісності, як-от `@intlayer/next-intl` чи `@intlayer/react-i18next`): ці місця виклику невидимі для аналізатора використання, тож purge видалив би поля, які код усе ще читає. Переписування імпортів залишається активним.
+
+**Раніші версії (до 9.2.1)** потребували `@intlayer/babel` і файл `babel.config.js`, що оголошує `intlayerPurgeBabelPlugin` та `intlayerMinifyBabelPlugin`. Цей файл більше не потрібен і його можна видалити.
+
  </Tab>
  <Tab value="vite">
 
@@ -447,6 +478,8 @@ export default config;
 
 > Мініфікація пропускається (skipped), коли `optimize` становить `false`, або коли `editor.enabled` становить `true` (візуальний редактор потребує оригінальних імен полів для їх редагування).
 
+> У Next.js мініфікація також пропускається, коли `@intlayer/swc` не встановлено або його неможливо завантажити (Next.js нижче 16.1.0). Плагін — це та половина, що переписує звернення у вихідному коді, тож перейменування словників без нього залишило б ваш код таким, що читає імена полів, яких більше немає.
+
 > Мініфікація також пропускається для словників, що завантажуються з `importMode: 'fetch'`, оскільки їхні JSON-дані постачаються з віддаленого API з оригінальними іменами полів — перейменування ключів на боці клієнта порушить зв'язок сервер/клієнт.
 
 ### Очищення (видалення невикористаних полів)
@@ -475,7 +508,7 @@ export default config;
 { "title": "…", "subtitle": "…" }
 ```
 
-> Очищення пропускається, коли `optimize` становить `false`, або коли `editor.enabled` становить `true`.
+> Очищення пропускається, коли `optimize` становить `false`, або коли `editor.enabled` становить `true`. У Next.js його додатково пропускають, коли `@intlayer/swc` недоступний і коли налаштовано викликачів з адаптерів сумісності.
 
 > Очищення також консервативно пропускається, коли вихідний файл не може бути розпарсений, або коли результат виклику `useIntlayer` присвоюється змінній і далі передається способами, які статичний аналізатор не може відстежити (наприклад, поширюється у вигляді spread-об'єкта чи передається як prop без деструктуризації). В таких випадках весь словник зберігається повністю.
 

package/docs/uk/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-07-11
+updatedAt: 2026-08-06
 title: Конфігурація
 description: Дізнайтеся, як налаштувати Intlayer для вашого додатка. Зрозумійте різні налаштування та параметри, доступні для адаптації Intlayer під ваші потреби.
 keywords:
@@ -14,6 +14,9 @@ slugs:
   - concept
   - configuration
 history:
+  - version: 9.1.3
+    date: 2026-08-06
+    changes: "Зробити `routing.enableProxy` трипозиційним: не задано (auto), `true`, `false`"
   - version: 9.0.0
     date: 2026-07-11
     changes: "Додано конфігурацію `analytics`"
@@ -235,6 +238,19 @@ const config: IntlayerConfig = {
      */
     mode: "prefix-no-default",
 
+    /**
+     * Вмикає проксі маршрутизації локалей Intlayer (middleware).
+     * Відповідає за визначення локалі, перенаправлення та перезапис URL у dev, preview та SSR.
+     * - не задано (auto): сервери dev і preview зберігають маршрутизацію за URL,
+     *   ігноруючи локаль, збережену в cookie та заголовках. Префікси й далі
+     *   розв’язуються, локаль і далі зберігається, а визначення Accept-Language
+     *   і далі діє. У продакшені поводиться як `true`.
+     * - true: повна поведінка в усіх середовищах.
+     * - false: маршрутизація локалей вимкнена.
+     * За замовчуванням: undefined (auto)
+     */
+    enableProxy: undefined,
+
     /**
      * Де зберігається вибрана користувачем локаль.
      * Варіанти: 'cookie', 'localStorage', 'sessionStorage', 'header' або їх масив.
@@ -713,13 +729,14 @@ export default config;
 
 Налаштування для контролю поведінки маршрутизації, включаючи структуру URL, зберігання локалі та керування проміжним ПЗ.
 
-| Поле       | Опис                                                                                                                                                                                                            | Тип                                                                                                                                                                                                          | За замовчуванням       | Приклад                                                                                                                                                                                        | Примітки                                                                                                                                                                                                                                                                                         |
-| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `mode`     | Режим структури URL для керування локаллю.                                                                                                                                                                      | `'prefix-no-default'` &#124; <br/> `'prefix-all'` &#124; <br/> `'no-prefix'` &#124; <br/> `'search-params'`                                                                                                  | `'prefix-no-default'`  | `'prefix-no-default'`: `/dashboard` (en) або `/fr/dashboard` (fr). `'prefix-all'`: `/en/dashboard` . `'no-prefix'`: локаль керується іншим способом. `'search-params'`: `/dashboard?locale=fr` | Не впливає на керування файлами cookie або локальне сховище.                                                                                                                                                                                                                                     |
-| `storage`  | Конфігурація для зберігання локалі на клієнті.                                                                                                                                                                  | `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 }]`                                                                                                             | Див. таблицю параметрів зберігання нижче.                                                                                                                                                                                                                                                        |
-| `basePath` | Базовий шлях для URL додатка.                                                                                                                                                                                   | `string`                                                                                                                                                                                                     | `''`                   | `'/my-app'`                                                                                                                                                                                    | Якщо ваш додаток знаходиться за адресою `https://example.com/my-app`, basePath - `'/my-app'`, що вказує на URL `https://example.com/my-app/en` .                                                                                                                                                 |
-| `rewrite`  | Власні правила перенаправлення URL для зміни стандартного режиму маршрутизації для певних шляхів. Підтримує динамічні параметри `[param]`.                                                                      | `Record<string, StrictModeLocaleMap<string>>`                                                                                                                                                                | `undefined`            | Див. приклад нижче                                                                                                                                                                             | • Правила перенаправлення мають вищий пріоритет, ніж `mode`.<br/>• Працює з Next.js та Vite.<br/>• `getLocalizedUrl()` автоматично застосовує відповідні правила.<br/>• Див. [Власні перенаправлення URL](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/custom_url_rewrites.md). |
-| `domains`  | Відображає локалі на імена хостів доменів для маршрутизації на основі доменів. Якщо встановлено, URL для цієї локалі використовують цей домен як базу (абсолютний URL), і префікс локалі не додається до шляху. | `Partial<Record<Locale, string>>`                                                                                                                                                                            | `undefined`            | `{ zh: 'intlayer.zh', fr: 'intlayer.org' }`                                                                                                                                                    | • Протокол за замовчуванням - `https://`, якщо він не вказаний у імені хоста.<br/>• Сам домен ідентифікує локаль, тому префікс `/zh/` не додається.<br/>• `getLocalizedUrl('/', 'zh')` повертає `https://intlayer.zh/`.                                                                          |
+| Поле          | Опис                                                                                                                                                                                                            | Тип                                                                                                                                                                                                          | За замовчуванням       | Приклад                                                                                                                                                                                        | Примітки                                                                                                                                                                                                                                                                                                                                                                |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`        | Режим структури URL для керування локаллю.                                                                                                                                                                      | `'prefix-no-default'` &#124; <br/> `'prefix-all'` &#124; <br/> `'no-prefix'` &#124; <br/> `'search-params'`                                                                                                  | `'prefix-no-default'`  | `'prefix-no-default'`: `/dashboard` (en) або `/fr/dashboard` (fr). `'prefix-all'`: `/en/dashboard` . `'no-prefix'`: локаль керується іншим способом. `'search-params'`: `/dashboard?locale=fr` | Не впливає на керування файлами cookie або локальне сховище.                                                                                                                                                                                                                                                                                                            |
+| `enableProxy` | Вмикає проксі маршрутизації локалей Intlayer (middleware).                                                                                                                                                      | `boolean` &#124; <br/> `undefined`                                                                                                                                                                           | `undefined` (auto)     | `true`                                                                                                                                                                                         | • Не задано (auto): сервери dev і preview ігнорують локаль із cookie/заголовків як джерело перенаправлення; префікси, збереження локалі та визначення `Accept-Language` продовжують діяти. У продакшені поводиться як `true`.<br/>• `true`: повна поведінка всюди.<br/>• `false`: маршрутизація локалей вимкнена. У Next.js middleware `intlayerProxy` стає наскрізним. |
+| `storage`     | Конфігурація для зберігання локалі на клієнті.                                                                                                                                                                  | `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 }]`                                                                                                             | Див. таблицю параметрів зберігання нижче.                                                                                                                                                                                                                                                                                                                               |
+| `basePath`    | Базовий шлях для URL додатка.                                                                                                                                                                                   | `string`                                                                                                                                                                                                     | `''`                   | `'/my-app'`                                                                                                                                                                                    | Якщо ваш додаток знаходиться за адресою `https://example.com/my-app`, basePath - `'/my-app'`, що вказує на URL `https://example.com/my-app/en` .                                                                                                                                                                                                                        |
+| `rewrite`     | Власні правила перенаправлення URL для зміни стандартного режиму маршрутизації для певних шляхів. Підтримує динамічні параметри `[param]`.                                                                      | `Record<string, StrictModeLocaleMap<string>>`                                                                                                                                                                | `undefined`            | Див. приклад нижче                                                                                                                                                                             | • Правила перенаправлення мають вищий пріоритет, ніж `mode`.<br/>• Працює з Next.js та Vite.<br/>• `getLocalizedUrl()` автоматично застосовує відповідні правила.<br/>• Див. [Власні перенаправлення URL](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/custom_url_rewrites.md).                                                                        |
+| `domains`     | Відображає локалі на імена хостів доменів для маршрутизації на основі доменів. Якщо встановлено, URL для цієї локалі використовують цей домен як базу (абсолютний URL), і префікс локалі не додається до шляху. | `Partial<Record<Locale, string>>`                                                                                                                                                                            | `undefined`            | `{ zh: 'intlayer.zh', fr: 'intlayer.org' }`                                                                                                                                                    | • Протокол за замовчуванням - `https://`, якщо він не вказаний у імені хоста.<br/>• Сам домен ідентифікує локаль, тому префікс `/zh/` не додається.<br/>• `getLocalizedUrl('/', 'zh')` повертає `https://intlayer.zh/`.                                                                                                                                                 |
 
 **Приклад `rewrite`**:
 

package/docs/uk/dictionary/nesting.md

@@ -68,6 +68,53 @@ export default firstDictionary;
 }
 ```
 
+### Посилання з Nest
+
+Тепер створіть ще один модуль контенту, який використовує функцію `nest` для посилання на вищезазначений контент. Ви можете посилатися на весь контент або на конкретне вкладене значення:
+
+```typescript fileName="secondDictionary.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+import { nest, type Dictionary } from "intlayer";
+
+const myNestingContent = {
+  key: "key_of_my_second_dictionary",
+  content: {
+    // Посилається на весь словник:
+    fullNestedContent: nest("key_of_my_first_dictionary"),
+    // Посилається на конкретне вкладене значення:
+    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"
+      }
+    }
+  }
+}
+```
+
+Як другий параметр, ви можете вказати шлях до вкладеного значення в цьому контенті. Якщо шлях не вказаний, повертається весь контент посилаючого словника.
+
 ## Налаштування вкладення
 
 <Tabs group="framework">
@@ -262,36 +309,6 @@ document.getElementById("nested")!.textContent = content.partialNestedContent;
   </Tab>
 </Tabs>
 
-## Використання вкладення з React Intlayer
-
-Щоб використовувати вкладений вміст у React-компоненті, скористайтеся хуком `useIntlayer` з пакету `react-intlayer`. Цей хук отримує відповідний вміст на основі вказаного ключа. Ось приклад того, як його використовувати:
-
-```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)}
-        {/* Вивід: {"content": "content", "subContent": {"contentNumber": 0, "contentString": "string"}} */}
-      </p>
-      <p>
-        Часткове вкладене значення: {partialNestedContent}
-        {/* Вивід: 0 */}
-      </p>
-    </div>
-  );
-};
-
-export default NestComponent;
-```
-
 ## Додаткові ресурси
 
 Для детальнішої інформації щодо конфігурації та використання зверніться до наступних ресурсів: