@intlayer/docs 9.1.3 → 9.3.0

package/docs/ru/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-тестирование
+  - Аудитория
+  - Интернационализация
+  - Документация
+  - 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` объединяет в пакеты три типа анонимных событий:
+
+| Событие            | Где фиксируется                           | О чем оно говорит                                                                                                          |
+| ------------------ | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `page_view`        | На уровне провайдера (`IntlayerProvider`) | Какую страницу и локаль просмотрел пользователь при начальной загрузке, смене маршрута или смене локали.                   |
+| `content_exposure` | На уровне узла (`useIntlayer` / плагины)  | Какой ключ словаря / путь к ключу был фактически разрешен и отображен — и, если это часть эксперимента, какой **вариант**. |
+| `conversion`       | Везде, где вызывается `useConversion()`   | Достижение цели (регистрация, клик, покупка...), связанное с A/B-вариантом, который видел пользователь в этой сессии.      |
+
+События собираются в памяти и отправляются как **один пакетный запрос примерно каждые 20 секунд** — а не при каждом нажатии клавиши или рендеринге — поэтому аналитика никогда не влияет на время первого рендеринга и не добавляет запросы на каждое взаимодействие.
+
+## Как это работает для A/B-тестирования контента
+
+Intlayer уже позволяет вам объявлять [Варианты](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/dynamic_dictionaries/index.md) контента (например, словарь `hero-banner` с вариантами `control` и `black_friday`). `@intlayer/analytics` замыкает цикл:
+
+1. `getVariant(experimentKey, variants)` детерминированно назначает каждую анонимную сессию варианту — это чистая функция от ID сессии и ключа эксперимента, поэтому назначение **стабильно на протяжении всей сессии** и не требует **серверных запросов** до первого рендеринга (без мерцания и сдвигов макета).
+2. Каждое событие `content_exposure` содержит показанный `variant`.
+3. `useConversion()` позволяет связать цель (например, `"cta_click"`) с этим вариантом.
+4. Эндпоинт результатов экспериментов в дашборде сравнивает коэффициенты конверсии по вариантам, включая статистическую значимость (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` автоматически:
+
+- инициализирует клиент аналитики при монтировании,
+- записывает `page_view` при начальной загрузке,
+- записывает `page_view` при каждой смене локали,
+- запускает цикл очистки (flush) с интервалом около 20 с и отправляет оставшиеся события при размонтировании / закрытии вкладки (через `navigator.sendBeacon`, с откатом на `fetch(..., { keepalive: true })`).
+
+### Автоматическое отслеживание на уровне узла
+
+Каждый раз, когда `useIntlayer` разрешает фрагмент контента для отображения, интерпретатор сообщает о событии `content_exposure` для этого точного `dictionaryKey` + пути к ключу + локали — опять же, никаких изменений в коде не требуется. Повторяющиеся показы одного и того же узла в пределах окна очистки объединяются в одно событие со счетчиком (`count`), поэтому список, перерисовывающийся 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; сервер когда-либо сохраняет только **SHA-256 хэш** этого id — никогда сам id и никогда IP-адрес.
+- **Приблизительное местоположение**: только код страны, полученный из заголовков геолокации CDN (`cf-ipcountry`, `x-vercel-ip-country`, ...) — IP не считывается и не сохраняется.
+- **URL исключают параметры поиска** по умолчанию, поэтому строки запроса никогда не фиксируются.
+- **Семплирование**: `sampleRate` позволяет сохранять только часть событий показа контента в приложениях с высоким трафиком.
+- **Пакетная передача**: один запрос примерно каждые 20 секунд (`flushInterval`) или раньше, если буфер заполнен (`maxBufferSize`) — никогда не отправляется один запрос на каждое событие.
+
+### Нулевые затраты, если не установлено
+
+`@intlayer/analytics` следует тому же паттерну опциональных зависимостей, что и `@intlayer/editor`:
+
+- каждая точка интеграции загружает пакет через **динамический `import()`, обернутый в `try/catch`** — приложение, которое никогда не устанавливает `@intlayer/analytics`, не увеличивает размер сборки (bundle) и не тратит ресурсы во время выполнения, а также никогда не видит ошибок;
+- переменная окружения времени компиляции (`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 дней**.
+- **Просмотры страниц** за выбранное окно.
+- **График динамики** уникальных посетителей по дням.
+- Вкладки с разбивкой по **Локалям** и **Местоположению**, ранжирующие вашу аудиторию по локали и по стране.
+
+## Справочник API бэкенда
+
+Все эндпоинты для чтения требуют аутентификации; прием данных публичный и ассоциируется по `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/ru/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/ru/dynamic_dictionaries/index.md)
+- [Intlayer CMS - CMS SDK](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_CMS.md)
+- [Визуальный редактор Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_visual_editor.md)
+- [Справочник по конфигурации](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/configuration.md)
+- [Руководство по самостоятельному хостингу (Self-Hosting)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/self_hosting.md)

package/docs/ru/autoFill.md

@@ -75,11 +75,30 @@ Intlayer также будет учитывать следующую инстр
 
 При использовании опции пути для записи в другой файл механизм заполнения работает через отношение _master-slave_ между файлами объявления содержимого. Основной файл (master) служит источником истины, и при его обновлении Intlayer автоматически применит эти изменения к производным (заполненным) файлам объявления, указанным в пути.
 
-# Переводы файлов декларации автозаполнения контента
+### Кастомизация по локалям
 
-**Файлы декларации автозаполнения контента**, это способ ускорить ваш процесс разработки.
+Вы также можете кастомизировать поведение для каждой локали, используя объект:
 
-Механизм автозаполнения работает через _мастер-слейв_ отношения между файлами декларации контента. Когда основной (мастер) файл обновляется, Intlayer автоматически применяет эти изменения к производным (автозаполненным) файлам декларации.
+```ts fileName="intlayer.config.ts"
+const config: IntlayerConfig = {
+  content: {
+    internationalization: {
+      locales: [Locales.ENGLISH, Locales.FRENCH, Locales.POLISH],
+      defaultLocale: Locales.ENGLISH,
+      requiredLocales: [Locales.ENGLISH], // Рекомендуется, чтобы избежать Property 'pl' is missing in type '{ en: string; xxx } on your t function if
+    },
+  },
+  dictionary: {
+    fill: {
+      en: true, // Заполнить и отредактировать текущий файл для английского языка
+      fr: "./translations/fr.json", // Создать отдельный файл для французского языка
+      es: false, // Отключить заполнение для испанского языка
+    },
+  },
+};
+```
+
+Это позволяет вам иметь разные поведения заполнения для разных локалей в одном проекте.
 
 ```ts fileName="src/components/example/example.content.ts"
 import { Locales, type Dictionary } from "intlayer";
@@ -87,16 +106,16 @@ import { Locales, type Dictionary } from "intlayer";
 const exampleContent = {
   key: "example",
   locale: Locales.ENGLISH,
-  autoFill: "./example.content.json",
+  fill: "./example.content.json",
   content: {
-    contentExample: "Это пример контента", // пример контента
+    contentExample: "This is an example of content",
   },
 } satisfies Dictionary;
 
 export default exampleContent;
 ```
 
-Вот [файл декларации контента для каждого локаля](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/per_locale_file.md), использующий инструкцию `autoFill`.
+Вот [файл объявления содержимого для каждой локали](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/per_locale_file.md) с использованием инструкции `fill`.
 
 Затем, когда вы выполните следующую команду:
 
@@ -116,7 +135,7 @@ pnpm intlayer fill --file 'src/components/example/example.content.ts'
 bun x intlayer fill --file 'src/components/example/example.content.ts'
 ```
 
-Intlayer автоматически сгенерирует производный файл декларации по пути `src/components/example/example.content.json`, заполняя все локали, которые ещё не объявлены в основном файле.
+Intlayer автоматически создаст производный файл объявления в `src/components/example/example.content.json`, заполняя все локали, которые еще не объявлены в основном файле.
 
 ```json5 fileName="src/components/example/example.content.json"
 {
@@ -133,7 +152,7 @@ Intlayer автоматически сгенерирует производны
 }
 ```
 
-После этого оба файла деклараций будут объединены в один словарь, доступный через стандартный хук `useIntlayer("example")` (react) / композицию (vue).
+После этого оба файла объявления будут объединены в один словарь, доступный с помощью стандартного хука `useIntlayer("example")` (react) / композабла (vue).
 
 ## Глобальная конфигурация
 

package/docs/ru/bundle_optimization.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-11-25
-updatedAt: 2026-06-07
+updatedAt: 2026-08-09
 title: Оптимизация размера сборки (bundle) 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; уточнен процесс работы плагинов (pipeline)"
@@ -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')` непрозрачным вызовом `useDictionary(hash)`, стирая информацию о ключе словаря, которая нужна плагинам purge и minify для определения того, какие поля используются.
 
@@ -205,9 +213,9 @@ Intlayer использует **компонентный подход**. В от
 | Помощник параметров          | Используется вместе с         |
 | :--------------------------- | :---------------------------- |
 | `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 для преобразований, но по-прежнему вычисляет (evaluates) `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;
 
 > Процесс минификации пропускается, если `optimize` установлен в `false` или когда `editor.enabled` имеет значение `true` (визуальный редактор требует сохранения оригинальных имен полей для возможности редактирования).
 
+> В Next.js минификация также пропускается, когда `@intlayer/swc` не установлен или не может быть загружен (Next.js ниже 16.1.0). Плагин — это та половина, которая переписывает обращения в исходном коде, поэтому переименование словарей без него оставило бы ваш код читающим имена полей, которых больше нет.
+
 > Минификация также пропускается для словарей, загружаемых через `importMode: 'fetch'`, поскольку их JSON выдается удаленным API с оригинальными именами полей — изменение ключей на клиентской стороне нарушит контракт сервер/клиент.
 
 ### Удаление неиспользуемых полей (Purging)
@@ -475,7 +508,7 @@ export default config;
 { "title": "…", "subtitle": "…" }
 ```
 
-> Процесс очистки пропускается, если `optimize` установлен в `false` или когда `editor.enabled` имеет значение `true`.
+> Процесс очистки пропускается, если `optimize` установлен в `false` или когда `editor.enabled` имеет значение `true`. В Next.js он дополнительно пропускается, когда `@intlayer/swc` недоступен и когда настроены вызывающие из адаптеров совместимости.
 
 > Очистка также отменяется из соображений надежности, когда исходный файл не удается разобрать (парсинг), или если результат работы `useIntlayer` присваивается переменной и передается способами, которые статический анализатор не может проконтролировать (например, spreading объекта, передача через prop без деструктуризации). В этих случаях сохраняется весь словарь целиком.
 

package/docs/ru/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-07-11
+updatedAt: 2026-08-06
 title: Конфигурация (Configuration)
 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, хранение языков и управление middleware.
 
-| Поле       | Описание                                                                                                                                                                                                                   | Тип                                                                                                                                                                                                          | По умолчанию           | Пример                                                                                                                                                                                           | Примечание                                                                                                                                                                                                                                                                                      |
-| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `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` | Не влияет на управление куками или хранилищем языков.                                                                                                                                                                                                                                           |
-| `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` | Не влияет на управление куками или хранилищем языков.                                                                                                                                                                                                                                                                                                                         |
+| `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/ru/dictionary/file.md

@@ -23,7 +23,9 @@ history:
 author: aymericzip
 ---
 
-# Содержимое файла / Встраивание файлов в Intlayer
+# Содержимое файлов / Встраивание файлов в Intlayer
+
+В Intlayer функция `file` позволяет встраивать содержимое внешних файлов в словарь. Такой подход гарантирует, что Intlayer распознает исходный файл, обеспечивая безупречную интеграцию с Visual Editor и CMS Intlayer.
 
 ## Как работает встраивание файлов