@intlayer/docs 8.12.1 → 8.12.3

package/docs/ru/bundle_optimization.md

@@ -1,10 +1,10 @@
 ---
 createdAt: 2025-11-25
-updatedAt: 2026-04-08
-title: Оптимизация размера бандла i18n и производительности
-description: Уменьшите размер бандла вашего приложения, оптимизируя контент интернационализации (i18n). Узнайте, как использовать tree shaking и lazy loading для словарей с помощью Intlayer.
+updatedAt: 2026-06-07
+title: Оптимизация размера сборки (bundle) i18n и производительности
+description: Уменьшите размер сборки вашего приложения за счет оптимизации контента интернационализации (i18n). Узнайте, как использовать tree shaking и ленивую загрузку (lazy loading) для словарей с помощью Intlayer.
 keywords:
-  - Оптимизация бандла
+  - Оптимизация сборки
   - Автоматизация контента
   - Динамический контент
   - Intlayer
@@ -16,33 +16,36 @@ slugs:
   - concept
   - bundle-optimization
 history:
+  - version: 8.12.0
+    date: 2026-06-07
+    changes: "Добавлены `intlayerPurgeBabelPlugin` и `intlayerMinifyBabelPlugin` для Babel/Webpack; уточнен процесс работы плагинов (pipeline)"
   - version: 8.7.0
     date: 2026-04-08
-    changes: "Добавлены опции `minify` и `purge` в конфигурацию сборки"
+    changes: "Добавлены параметры `minify` и `purge` в конфигурацию сборки"
 ---
 
-# Оптимизация размера бандла i18n и производительности
+# Оптимизация размера сборки i18n и производительности
 
-Одной из наиболее распространенных проблем традиционных i18n-решений, полагающихся на JSON-файлы, является управление размером контента. Если разработчики вручную не разделяют контент на пространства имен (namespaces), пользователи часто скачивают переводы для каждой страницы и, возможно, для каждого языка только для того, чтобы просмотреть одну страницу.
+Одной из самых распространенных проблем при использовании традиционных решений i18n, опирающихся на JSON-файлы, является управление размером контента. Если разработчики не разделяют контент на пространства имен (namespaces) вручную, пользователи часто вынуждены скачивать переводы для каждой страницы и, потенциально, для каждого языка только для того, чтобы просмотреть одну единственную страницу.
 
-Например, приложение с 10 страницами, переведенными на 10 языков, может привести к тому, что пользователь скачает контент 100 страниц, хотя ему нужна только **одна** (текущая страница на текущем языке). Это ведет к напрасной трате трафика и замедлению времени загрузки.
+Например, в приложении с 10 страницами, переведенными на 10 языков, пользователь может загрузить контент сразу для 100 страниц, хотя ему нужна только **одна** (текущая страница на текущем языке). Это приводит к напрасной трате пропускной способности и замедлению времени загрузки.
 
-**Intlayer решает эту проблему с помощью оптимизации на этапе сборки.** Он анализирует ваш код, чтобы определить, какие словари действительно используются в каждом компоненте, и внедряет только необходимый контент в ваш бандл.
+**Intlayer решает эту проблему посредством оптимизации во время сборки (build-time optimization).** Он анализирует ваш код, чтобы обнаружить, какие именно словари фактически используются в каждом компоненте, и встраивает в вашу сборку только необходимый контент.
 
-## Содержание
+## Оглавление
 
 <TOC />
 
-## Сканирование бандла
+## Анализ вашей сборки
 
-Анализ бандла - это первый шаг к выявлению "тяжелых" JSON-файлов и возможностей разделения кода. Эти инструменты генерируют визуальную древовидную карту (treemap) скомпилированного кода вашего приложения, позволяя вам точно увидеть, какие библиотеки занимают больше всего места.
+Анализ вашей сборки (бандла) — это первый шаг к выявлению «тяжелых» JSON-файлов и возможностей для разделения кода (code-splitting). Специализированные инструменты генерируют визуальное дерево (treemap) скомпилированного кода вашего приложения, что позволяет точно увидеть, какие библиотеки потребляют больше всего места.
 
 <Tabs>
  <Tab value="vite">
 
 ### Vite / Rollup
 
-Vite использует Rollup под капотом. Плагин `rollup-plugin-visualizer` генерирует интерактивный HTML-файл, показывающий размер каждого модуля в вашем графе.
+Vite использует Rollup «под капотом». Плагин `rollup-plugin-visualizer` генерирует интерактивный HTML-файл, отображающий размер каждого модуля в вашем графе.
 
 ```bash
 npm install -D rollup-plugin-visualizer
@@ -55,7 +58,7 @@ import { visualizer } from "rollup-plugin-visualizer";
 export default defineConfig({
   plugins: [
     visualizer({
-      open: true, // Автоматически открыть отчет в браузере
+      open: true, // Автоматически открывать отчет в браузере
       filename: "stats.html",
       gzipSize: true,
       brotliSize: true,
@@ -69,7 +72,7 @@ export default defineConfig({
 
 ### Next.js (Turbopack)
 
-Для проектов, использующих App Router и Turbopack, Next.js предоставляет встроенный экспериментальный анализатор, не требующий дополнительных зависимостей.
+Для проектов, использующих App Router и Turbopack, Next.js предоставляет встроенный экспериментальный анализатор, который не требует установки дополнительных зависимостей.
 
 ```bash packageManager='npm'
 npx next experimental-analyze
@@ -92,7 +95,7 @@ bun next experimental-analyze
 
 ### Next.js (Webpack)
 
-Если вы используете стандартный сборщик Webpack в Next.js, используйте официальный анализатор бандлов. Запустите его, установив переменную окружения во время сборки (build time).
+Если вы используете стандартный сборщик Webpack в Next.js, воспользуйтесь официальным анализатором сборки. Его можно запустить, установив переменную окружения во время сборки.
 
 ```bash packageManager='npm'
 npm install -D @next/bundle-analyzer
@@ -116,7 +119,7 @@ const withBundleAnalyzer = require("@next/bundle-analyzer")({
 });
 
 module.exports = withBundleAnalyzer({
-  // Ваша конфигурация Next.js
+  // Ваш конфиг Next.js
 });
 ```
 
@@ -131,7 +134,7 @@ ANALYZE=true npm run build
 
 ### Стандартный Webpack
 
-Для Create React App (ejected), Angular или кастомных настроек Webpack используйте отраслевой стандарт `webpack-bundle-analyzer`.
+Для Create React App (ejected), Angular или пользовательских конфигураций Webpack используйте стандартный плагин `webpack-bundle-analyzer`.
 
 ```bash packageManager='npm'
 npm install -D webpack-bundle-analyzer
@@ -168,16 +171,53 @@ export default {
 
 ## Как это работает
 
-Intlayer использует **подход на уровне компонентов**. В отличие от глобальных JSON-файлов, ваш контент определяется рядом с вашими компонентами или внутри них. В процессе сборки Intlayer:
+Intlayer использует **компонентный подход**. В отличие от глобальных JSON-файлов, ваш контент определяется рядом с вашими компонентами или внутри них. В процессе сборки Intlayer выполняет следующие действия:
 
-1.  **Анализирует** ваш код на наличие вызовов `useIntlayer`.
-2.  **Собирает** соответствующий контент словаря.
-3.  **Заменяет** вызов `useIntlayer` оптимизированным кодом на основе вашей конфигурации.
+1. **Анализирует** ваш код, чтобы найти вызовы `useIntlayer`.
+2. **Создает** соответствующий контент словаря.
+3. **Заменяет** вызов `useIntlayer` оптимизированным кодом на основе вашей конфигурации.
 
-Это гарантирует, что:
+Это гарантирует следующее:
 
-- Если компонент не импортирован, его контент не включается в бандл (удаление мертвого кода).
-- Если компонент загружается лениво (lazy-loading), его контент также загружается лениво.
+- Если компонент не импортируется, его контент не включается в сборку (устранение мертвого кода — Dead Code Elimination).
+- Если компонент загружается лениво (lazy-loaded), его контент также загружается лениво.
+
+## Справочник по плагинам
+
+Оптимизация сборки Intlayer разделена на несколько дискретных плагинов, каждый из которых имеет свою единственную ответственность. Понимание того, что делает каждый плагин, предотвращает путаницу при их настройке.
+
+### Плагины Babel (`@intlayer/babel`)
+
+Они используются непосредственно в `babel.config.js` для сборок на базе Webpack (Next.js с Babel, CRA, пользовательский Webpack и т.д.).
+
+| Плагин                        | Что делает                                                                                                                              |
+| :---------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
+| `intlayerExtractBabelPlugin`  | Сканирует `.content.ts` файлы и записывает скомпилированные словари в `.intlayer/`                                                      |
+| `intlayerOptimizeBabelPlugin` | Переписывает `useIntlayer('key')` → `useDictionary(hash)` и внедряет (import) соответствующий словарь                                   |
+| `intlayerPurgeBabelPlugin`    | Сканирует все исходные файлы, удаляет **неиспользуемые поля контента** из скомпилированных `.intlayer/**/*.json` файлов словарей        |
+| `intlayerMinifyBabelPlugin`   | **Переименовывает ключи полей контента** в короткие буквенные алиасы (например, `title` → `a`) как в JSON-файлах, так и в исходном коде |
+
+> **Порядок плагинов имеет значение.** В вашем `babel.config.js` плагины purge и minify должны быть указаны **до** плагина optimize. Оптимизация (optimize) заменяет `useIntlayer('key')` непрозрачным вызовом `useDictionary(hash)`, стирая информацию о ключе словаря, которая нужна плагинам purge и minify для определения того, какие поля используются.
+
+Каждый плагин Babel имеет соответствующий помощник параметров (options helper), который однократно считывает ваш `intlayer.config.ts` во время загрузки конфигурации и возвращает предварительно разрешенные (resolved) значения:
+
+| Помощник параметров          | Используется вместе с         |
+| :--------------------------- | :---------------------------- |
+| `getExtractPluginOptions()`  | `intlayerExtractBabelPlugin`  |
+| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
+| `getPurgePluginOptions()`    | `intlayerPurgeBabelPlugin`    |
+| `getMinifyPluginOptions()`   | `intlayerMinifyBabelPlugin`   |
+
+### Плагины Vite (`vite-intlayer`)
+
+Пользователям Vite **не нужно настраивать их напрямую**. Они автоматически подключаются при вызове `withIntlayer()` в `vite.config.ts`. Флаги `build.purge` и `build.minify` в `intlayer.config.ts` включают соответствующее поведение без какой-либо дополнительной регистрации плагинов.
+
+| Внутренний Vite плагин | Эквивалентное поведение                                                                                      |
+| :--------------------- | :----------------------------------------------------------------------------------------------------------- |
+| Usage analyzer         | То же самое, что и анализ плагина `intlayerPurgeBabelPlugin`                                                 |
+| Dictionary prune       | То же самое, что и запись JSON плагином `intlayerPurgeBabelPlugin`                                           |
+| Dictionary minify      | То же самое, что и запись JSON плагином `intlayerMinifyBabelPlugin`                                          |
+| Babel transform        | То же самое, что и переименование исходного кода `intlayerMinifyBabelPlugin` + `intlayerOptimizeBabelPlugin` |
 
 ## Настройка по платформам
 
@@ -186,9 +226,9 @@ Intlayer использует **подход на уровне компонен
 
 ### Next.js
 
-Для трансформации Next.js требуется плагин `@intlayer/swc`, так как Next.js использует SWC для сборки.
+Next.js требует использования плагина `@intlayer/swc` для оптимизации (перезаписи импортов), так как Next.js использует SWC при сборке.
 
-> Этот плагин не устанавливается по умолчанию, так как плагины SWC для Next.js все еще находятся в стадии эксперимента. Это может измениться в будущем.
+> Этот плагин не устанавливается по умолчанию, поскольку плагины SWC всё еще находятся на стадии эксперимента для Next.js. Это может измениться в будущем.
 
 ```bash packageManager="npm"
 npm install -D @intlayer/swc
@@ -206,21 +246,63 @@ pnpm add -D @intlayer/swc
 bun add -d @intlayer/swc
 ```
 
-После установки Intlayer автоматически обнаружит и будет использовать плагин.
+После установки Intlayer автоматически обнаружит и использует этот плагин.
+
+Для выполнения **удаления (purge) и минификации (minify)** (удаления полей и их переименования), установите `@intlayer/babel` параллельно с вышеуказанным и добавьте плагины Babel. Поскольку Next.js использует SWC для преобразований, но по-прежнему вычисляет (evaluates) `babel.config.js` для конфигурации плагинов, плагины Babel запускаются в качестве предварительного этапа до SWC.
+
+```bash packageManager="npm"
+npm install -D @intlayer/babel
+```
+
+```javascript fileName="babel.config.js"
+const {
+  intlayerPurgeBabelPlugin,
+  intlayerMinifyBabelPlugin,
+  getPurgePluginOptions,
+  getMinifyPluginOptions,
+} = require("@intlayer/babel");
+
+module.exports = {
+  presets: ["next/babel"],
+  plugins: [
+    // Purge: удаляет неиспользуемые поля контента из .intlayer/**/*.json
+    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],
+    // Minify: переименовывает ключи полей контента в JSON + в исходном коде
+    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],
+    // Примечание: intlayerOptimizeBabelPlugin ЗДЕСЬ НЕ НУЖЕН, потому что
+    // @intlayer/swc самостоятельно обрабатывает переписывание useIntlayer → useDictionary.
+  ],
+};
+```
 
  </Tab>
  <Tab value="vite">
 
 ### Vite
 
-Vite использует плагин `@intlayer/babel`, который включен как зависимость `vite-intlayer`. Оптимизация включена по умолчанию. Ничего больше делать не нужно.
+Vite использует плагин `@intlayer/babel`, который включен в качестве зависимости к `vite-intlayer`. Полный цикл оптимизации (pipeline) — перезапись импортов, удаление (purge) и минификация (minify) — включен по умолчанию и не требует регистрации дополнительных плагинов.
+
+Включите purge и minify, установив соответствующие флаги в `intlayer.config.ts`:
+
+```typescript fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  build: {
+    purge: true, // удаляет неиспользуемые поля контента из собранных JSON
+    minify: true, // переименовывает ключи полей контента в короткие алиасы
+  },
+};
+
+export default config;
+```
 
  </Tab>
  <Tab value="webpack">
 
-### Webpack
+### Webpack (и Next.js с Babel)
 
-Чтобы включить оптимизацию бандла с помощью Intlayer в Webpack, вам необходимо установить и настроить соответствующий плагин Babel (`@intlayer/babel`) или SWC (`@intlayer/swc`).
+Установите `@intlayer/babel`:
 
 ```bash packageManager="npm"
 npm install -D @intlayer/babel
@@ -238,14 +320,37 @@ pnpm add -D @intlayer/babel
 bun add -d @intlayer/babel
 ```
 
-```typescript fileName="babel.config.js"
+Добавьте все четыре плагина в `babel.config.js` в правильном порядке:
+
+```javascript fileName="babel.config.js"
 const {
-  getOptimizePluginOptions,
+  intlayerExtractBabelPlugin,
+  intlayerPurgeBabelPlugin,
+  intlayerMinifyBabelPlugin,
   intlayerOptimizeBabelPlugin,
+  getExtractPluginOptions,
+  getPurgePluginOptions,
+  getMinifyPluginOptions,
+  getOptimizePluginOptions,
 } = require("@intlayer/babel");
 
 module.exports = {
-  plugins: [[intlayerOptimizeBabelPlugin, getOptimizePluginOptions()]],
+  plugins: [
+    // Extract: компилирует файлы .content.ts → .intlayer/**/*.json
+    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
+
+    // Purge: удаляет неиспользуемые поля из .intlayer/**/*.json
+    //    (считывает флаг build.purge из intlayer.config.ts)
+    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],
+
+    // Minify: переименовывает ключи в JSON + исходном коде
+    //    (считывает флаг build.minify из intlayer.config.ts)
+    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],
+
+    // Optimize: переписывает useIntlayer('key') → useDictionary(hash)
+    //    Должен быть последним, поскольку удаляет ключ словаря.
+    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
+  ],
 };
 ```
 
@@ -254,57 +359,62 @@ module.exports = {
 
 ## Конфигурация
 
-Вы можете управлять тем, как Intlayer оптимизирует ваш бандл, с помощью свойства `build` в вашем `intlayer.config.ts`.
+Вы можете управлять тем, как Intlayer оптимизирует вашу сборку, через свойство `build` в вашем `intlayer.config.ts`.
 
 ```typescript fileName="intlayer.config.ts"
 import { Locales, type IntlayerConfig } from "intlayer";
 
 const config: IntlayerConfig = {
   internationalization: {
-    locales: [Locales.ENGLISH, Locales.FRENCH],
+    locales: [Locales.ENGLISH, Locales.RUSSIAN],
     defaultLocale: Locales.ENGLISH,
   },
   dictionary: {
     importMode: "dynamic",
   },
   build: {
-    /**
-     * Минифицировать словари для уменьшения размера бандла.
-     */
-     minify: true;
-
-    /**
-     * Удалять неиспользуемые ключи в словарях (purge)
-     */
-     purge: true;
-
-    /**
-     * Указывает, должна ли сборка проверять типы TypeScript
-     */
-    checkTypes: false;
+    // Заменяет вызовы useIntlayer() на прямые импорты словарей во время сборки.
+    // undefined = auto (активно в продакшене), true = всегда, false = никогда.
+    optimize: undefined,
+
+    // Переименовывает ключи полей контента в скомпилированных словарях в короткие
+    // буквенные алиасы (например, title → a). Уменьшает размер JSON; требует optimize.
+    minify: true,
+
+    // Удаляет поля контента, к которым никогда не происходит обращение в исходном коде.
+    // Требует optimize.
+    purge: true,
   },
 };
 
 export default config;
 ```
 
-> В подавляющем большинстве случаев рекомендуется оставлять значение по умолчанию для параметра `optimize`.
+> Во многих случаях рекомендуется оставлять значение по умолчанию (`undefined`) для параметра `optimize`.
 
-> Подробности см. в документации по конфигурации: [Конфигурация](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/configuration.md)
+> См. справочник конфигурации со всеми опциями: [Конфигурация](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/configuration.md)
 
-### Опции сборки
+### Параметры сборки (Build Options)
 
-В объекте конфигурации `build` доступны следующие опции:
+| Свойство       | Тип                    | По умолчанию | Описание                                                                                                                                                                                            |
+| :------------- | :--------------------- | :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`optimize`** | `boolean \| undefined` | `undefined`  | Включает фазу перезаписи импортов. `undefined` = активно только для продакшен-сборок. `false` также отключает purge и minify.                                                                       |
+| **`minify`**   | `boolean`              | `false`      | Переименовывает ключи полей контента в скомпилированных JSON-файлах в короткие буквенные алиасы. Также перезаписывает соответствующие обращения в исходном коде. Не работает при `optimize: false`. |
+| **`purge`**    | `boolean`              | `false`      | Удаляет поля контента из скомпилированных JSON-файлов, к которым не происходит статического обращения в коде. Не работает при `optimize: false`.                                                    |
 
-| Свойство       | Тип       | По умолчанию | Описание                                                                                                                                                                                           |
-| :------------- | :-------- | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **`optimize`** | `boolean` | `undefined`  | Управляет включением оптимизации сборки. Если `true`, Intlayer заменяет вызовы словаря оптимизированными вставками. Если `false`, оптимизация отключена. В идеале в продакшене должно быть `true`. |
-| **`minify`**   | `boolean` | `false`      | Минифицировать ли словари для уменьшения размера бандла.                                                                                                                                           |
-| **`purge`**    | `boolean` | `false`      | Удалять ли неиспользуемые ключи в словарях.                                                                                                                                                        |
+### Минификация (Minification) — переименование ключей полей
 
-### Минификация
+Параметр `build.minify` **не** занимается минификацией вашего JavaScript-бандла — с этой задачей должен справляться ваш сборщик. Вместо этого он уменьшает размер JSON-файлов скомпилированных словарей, заменяя каждый заданный пользователем ключ на короткий буквенный алиас:
 
-Минификация словарей удаляет ненужные пробелы, комментарии и уменьшает размер содержимого JSON. Это особенно полезно для больших словарей.
+```
+// Перед минификацией
+{ "title": "Привет", "subtitle": "Мир" }
+
+// После минификации
+{ "a": "Привет", "b": "Мир" }
+```
+
+Аналогичное переименование применяется ко всем обращениям к свойствам в вашем исходном коде, поэтому `content.title` в скомпилированном выходе превратится в `content.a`. Поведение приложения во время выполнения остается абсолютно идентичным.
 
 ```typescript fileName="intlayer.config.ts"
 import type { IntlayerConfig } from "intlayer";
@@ -318,11 +428,13 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-> Примечание: Минификация игнорируется, если `optimize` отключен или если включен Визуальный редактор (так как редактору требуется полный контент для возможности редактирования).
+> Процесс минификации пропускается, если `optimize` установлен в `false` или когда `editor.enabled` имеет значение `true` (визуальный редактор требует сохранения оригинальных имен полей для возможности редактирования).
+
+> Минификация также пропускается для словарей, загружаемых через `importMode: 'fetch'`, поскольку их JSON выдается удаленным API с оригинальными именами полей — изменение ключей на клиентской стороне нарушит контракт сервер/клиент.
 
-### Очистка (Purging)
+### Удаление неиспользуемых полей (Purging)
 
-Очистка гарантирует, что в финальный бандл словарей будут включены только те ключи, которые действительно используются в вашем коде. Это может значительно уменьшить размер вашего бандла, если у вас есть большие словари со множеством ключей, которые используются не во всех частях вашего приложения.
+Параметр `build.purge` анализирует, к каким полям контента фактически обращается ваш исходный код, и удаляет все остальные поля из скомпилированных JSON-файлов.
 
 ```typescript fileName="intlayer.config.ts"
 import type { IntlayerConfig } from "intlayer";
@@ -336,34 +448,50 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-> Примечание: Очистка игнорируется, если параметр `optimize` отключен.
+**Пример:** словарь с пятью полями, из которых в коде используются только два:
+
+```
+// До очистки (purge)
+{ "title": "…", "subtitle": "…", "cta": "…", "footer": "…", "badge": "…" }
+
+// После очистки (в коде используются только title и subtitle)
+{ "title": "…", "subtitle": "…" }
+```
+
+> Процесс очистки пропускается, если `optimize` установлен в `false` или когда `editor.enabled` имеет значение `true`.
+
+> Очистка также отменяется из соображений надежности, когда исходный файл не удается разобрать (парсинг), или если результат работы `useIntlayer` присваивается переменной и передается способами, которые статический анализатор не может проконтролировать (например, spreading объекта, передача через prop без деструктуризации). В этих случаях сохраняется весь словарь целиком.
 
 ### Режим импорта (Import Mode)
 
-Для больших приложений, включающих множество страниц и локалей, ваши JSON-файлы могут составлять значительную часть размера бандла. Intlayer позволяет вам контролировать способ загрузки словарей.
+Для крупных приложений, включающих несколько страниц и локалей, ваш JSON может составлять значительную часть размера вашей сборки (bundle). Intlayer позволяет вам контролировать способ загрузки словарей с помощью опции `importMode`.
+
+### Глобальное определение
 
-Режим импорта может быть определен по умолчанию глобально в вашем файле `intlayer.config.ts`.
+Режим импорта можно определить глобально в вашем файле `intlayer.config.ts`.
 
 ```typescript fileName="intlayer.config.ts"
 import type { IntlayerConfig } from "intlayer";
 
 const config: IntlayerConfig = {
-  build: {
-    minify: true,
+  dictionary: {
+    importMode: "dynamic", // Значение по умолчанию — 'static'
   },
 };
 
 export default config;
 ```
 
-А также для каждого словаря в ваших файлах `.content.{{ts|tsx|js|jsx|mjs|cjs|json|jsonc|json5}}`.
+### Определение на уровне словаря
+
+Вы можете переопределить режим импорта для отдельных словарей в их файлах `.content.{{ts|tsx|js|jsx|mjs|cjs|json|jsonc|json5|md|mdx|yaml|yml}}`.
 
 ```ts
 import { type Dictionary, t } from "intlayer";
 
 const appContent: Dictionary = {
   key: "app",
-  importMode: "dynamic", // Переопределить режим импорта по умолчанию
+  importMode: "dynamic", // Переопределяем глобальный режим импорта
   content: {
     // ...
   },
@@ -372,83 +500,103 @@ const appContent: Dictionary = {
 export default appContent;
 ```
 
-| Свойство         | Тип                                | По умолчанию | Описание                                                                                                                |
-| :--------------- | :--------------------------------- | :----------- | :---------------------------------------------------------------------------------------------------------------------- |
-| **`importMode`** | `'static'`, `'dynamic'`, `'fetch'` | `'static'`   | **Устарело**: Используйте `dictionary.importMode` вместо этого. Определяет, как загружаются словари (подробности ниже). |
+| Опция            | Тип                                | По умолчанию | Описание                                                                                                                 |
+| :--------------- | :--------------------------------- | :----------- | :----------------------------------------------------------------------------------------------------------------------- |
+| **`importMode`** | `'static'`, `'dynamic'`, `'fetch'` | `'static'`   | **Устарело**: Используйте `dictionary.importMode`. Определяет, каким образом загружаются словари (подробности см. ниже). |
 
-Настройка `importMode` определяет, как содержимое словаря внедряется в ваш компонент.
-Вы можете определить его глобально в файле `intlayer.config.ts` в объекте `dictionary` или переопределить для конкретного словаря в его файле `.content.ts`.
+Настройка `importMode` определяет, как контент словаря будет внедряться в ваш компонент. Эту настройку можно задать глобально в `intlayer.config.ts` (в объекте `dictionary`) или переопределить в файле `.content.ts` для каждого словаря.
 
-### 1. Статический режим (`default`)
+### 1. Статический режим (Static Mode - `default`)
 
-В статическом режиме Intlayer заменяет `useIntlayer` на `useDictionary` и внедряет словарь непосредственно в JavaScript бандл.
+В статическом режиме Intlayer заменяет `useIntlayer` на `useDictionary` и внедряет словарь непосредственно в пакет (bundle) JavaScript.
 
-- **Плюсы:** Мгновенный рендеринг (синхронный), отсутствие дополнительных сетевых запросов во время гидратации.
-- **Минусы:** Бандл включает переводы для **всех** доступных языков для этого конкретного компонента.
-- **Лучше всего для:** Одностраничных приложений (SPA).
+- **Плюсы:** Мгновенный рендеринг (синхронный), ноль дополнительных сетевых запросов во время гидратации (hydration).
+- **Минусы:** Сборка включает переводы для **всех** доступных языков, если они определены для данного компонента.
+- **Подходит для:** Одностраничных приложений (SPA).
 
-**Пример трансформированного кода:**
+**Пример измененного кода:**
 
 ```tsx
 // Ваш код
 const content = useIntlayer("my-key");
 
-// Оптимизированный код (Статический)
+// Оптимизированный код после преобразования (Static)
+// Это только иллюстрация, реальный код будет другим по соображениям оптимизации
 const content = useDictionary({
   key: "my-key",
   content: {
     nodeType: "translation",
     translation: {
       en: "My title",
-      fr: "Mon titre",
+      ru: "Мой заголовок",
     },
   },
 });
 ```
 
-### 2. Динамический режим
+### 2. Динамический режим (Dynamic Mode)
 
-В динамическом режиме Intlayer заменяет `useIntlayer` на `useDictionaryAsync`. Это использует `import()` (механизм типа Suspense) для ленивой загрузки конкретно JSON для текущей локали.
+В динамическом режиме Intlayer заменяет `useIntlayer` на `useDictionaryAsync`. Он использует `import()` (подобно механизму Suspense), чтобы применять ленивую загрузку конкретно JSON для текущей локали.
 
-- **Плюсы:** **Tree shaking на уровне локали.** Пользователь, просматривающий английскую версию, скачает _только_ английский словарь. Французский словарь никогда не загрузится.
-- **Минусы:** Вызывает сетевой запрос (загрузку ассета) для каждого компонента во время гидратации.
-- **Лучше всего для:** Больших текстовых блоков, статей или приложений с поддержкой многих языков, где размер бандла критичен.
+- **Плюсы:** **Tree shaking на уровне локали (языка).** Пользователь, просматривающий английскую версию, загрузит _только_ английский словарь. Русский словарь никогда не будет загружен.
+- **Минусы:** Вызывает сетевой запрос (получение ассетов) для каждого компонента во время гидратации.
+- **Подходит для:** Крупных текстовых блоков, статей или приложений с поддержкой большого числа языков, где размер сборки имеет критическое значение.
 
-**Пример трансформированного кода:**
+**Пример измененного кода:**
 
 ```tsx
 // Ваш код
 const content = useIntlayer("my-key");
 
-// Оптимизированный код (Динамический)
+// Иллюстрация оптимизированного кода (Dynamic)
+// Это только иллюстрация, реальный код будет отличаться
 const content = useDictionaryAsync({
   en: () =>
     import(".intlayer/dynamic_dictionary/my-key/en.json").then(
       (mod) => mod.default
     ),
-  fr: () =>
-    import(".intlayer/dynamic_dictionary/my-key/fr.json").then(
+  ru: () =>
+    import(".intlayer/dynamic_dictionary/my-key/ru.json").then(
       (mod) => mod.default
     ),
 });
 ```
 
-> При использовании `importMode: 'dynamic'`, если у вас на одной странице 100 компонентов используют `useIntlayer`, браузер попытается выполнить 100 отдельных загрузок. Чтобы избежать этого "водопада" запросов, группируйте контент в меньшее количество файлов `.content` (например, один словарь на раздел страницы), а не по одному на каждый мелкий компонент.
+> Если вы используете `importMode: 'dynamic'` и у вас есть 100 компонентов на одной странице, каждый из которых вызывает `useIntlayer`, браузер предпримет 100 отдельных попыток получения файлов. Чтобы избежать этого «водопада» запросов, группируйте контент в меньшем количестве файлов `.content` (например, один словарь на раздел страницы), а не создавайте их по одному на каждый атомарный компонент. Вы также можете использовать несколько файлов `.content` с одним и тем же ключом: Intlayer объединит их в один единый словарь.
 
 ### 3. Режим Fetch
 
-Ведет себя аналогично динамическому режиму, но сначала пытается получить словари из API Intlayer Live Sync. Если вызов API завершается неудачей или контент не помечен для живых обновлений, он переключается на динамический импорт.
+Данный режим работает аналогично динамическому режиму, но в первую очередь пытается получить словари из API синхронизации Intlayer Live Sync. Если вызов API не удается или контент не помечен для работы в реальном времени, происходит откат (fallback) к динамическому импорту.
+
+**Пример измененного кода:**
+
+```tsx
+// Ваш код
+const content = useIntlayer("my-key");
+
+// Иллюстрация оптимизированного кода (Fetch)
+const content = useDictionaryAsync({
+  en: () =>
+    fetch("https://intlayer.my-domain.com/dictionary/my-key/en").then((res) =>
+      res.json()
+    ),
+  ru: () =>
+    fetch("https://intlayer.my-domain.com/dictionary/my-key/ru").then((res) =>
+      res.json()
+    ),
+});
+```
 
-> Подробности см. в документации CMS: [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_CMS.md)
+> Подробнее смотрите в документации к CMS: [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_CMS.md)
 
-> В режиме fetch нельзя использовать очистку (purge) и минификацию.
+> В режиме fetch ни purge (очистка), ни minify (минификация) не применяются, поскольку исходный JSON отдается удаленным API с оригинальными названиями полей.
 
-## Резюме: Статический vs Динамический
+## Итог: Статический vs Динамический
 
-| Функция                          | Статический режим                          | Динамический режим                                  |
-| :------------------------------- | :----------------------------------------- | :-------------------------------------------------- |
-| **Размер JS бандла**             | Больше (включает все языки для компонента) | Меньше всего (только код, контента нет)             |
-| **Начальная загрузка**           | Мгновенно (контент уже в бандле)           | Небольшая задержка (загрузка JSON)                  |
-| **Сетевые запросы**              | 0 дополнительных запросов                  | 1 запрос на каждый словарь                          |
-| **Tree Shaking**                 | На уровне компонентов                      | На уровне компонентов + на уровне локалей           |
-| **Лучший вариант использования** | UI-компоненты, небольшие приложения        | Страницы с большим количеством текста, много языков |
+| Характеристика              | Статический режим (Static Mode)            | Динамический режим (Dynamic Mode)      |
+| :-------------------------- | :----------------------------------------- | :------------------------------------- |
+| **Размер сборки (JS)**      | Больше (включает все языки для компонента) | Минимальный (только код, без контента) |
+| **Первоначальная загрузка** | Мгновенная (контент в бандле)              | Небольшая задержка (загрузка JSON)     |
+| **Сетевые запросы**         | 0 дополнительных запросов                  | 1 запрос на каждый ключ словаря        |
+| **Tree Shaking**            | На уровне компонентов                      | На уровне компонентов и локалей        |
+| **Лучший сценарий**         | UI-компоненты, небольшие приложения        | Крупный текст, многоязычность          |