@intlayer/docs 9.4.1 → 9.4.3

package/docs/ru/bundle_optimization.md

@@ -43,139 +43,6 @@ author: aymericzip
 
 <TOC />
 
-## Анализ вашей сборки
-
-Анализ вашей сборки (бандла) — это первый шаг к выявлению «тяжелых» JSON-файлов и возможностей для разделения кода (code-splitting). Специализированные инструменты генерируют визуальное дерево (treemap) скомпилированного кода вашего приложения, что позволяет точно увидеть, какие библиотеки потребляют больше всего места.
-
-<Tabs>
- <Tab value="vite">
-
-### Vite / Rollup
-
-Vite использует Rollup «под капотом». Плагин `rollup-plugin-visualizer` генерирует интерактивный HTML-файл, отображающий размер каждого модуля в вашем графе.
-
-```bash
-npm install -D rollup-plugin-visualizer
-```
-
-```typescript fileName="vite.config.ts"
-import { defineConfig } from "vite";
-import { visualizer } from "rollup-plugin-visualizer";
-
-export default defineConfig({
-  plugins: [
-    visualizer({
-      open: true, // Автоматически открывать отчет в браузере
-      filename: "stats.html",
-      gzipSize: true,
-      brotliSize: true,
-    }),
-  ],
-});
-```
-
- </Tab>
- <Tab value="nextjs (turbopack)">
-
-### Next.js (Turbopack)
-
-Для проектов, использующих App Router и Turbopack, Next.js предоставляет встроенный экспериментальный анализатор, который не требует установки дополнительных зависимостей.
-
-```bash packageManager='npm'
-npx next experimental-analyze
-```
-
-```bash packageManager='yarn'
-yarn next experimental-analyze
-```
-
-```bash packageManager='pnpm'
-pnpm next experimental-analyze
-```
-
-```bash packageManager='bun'
-bun next experimental-analyze
-```
-
- </Tab>
- <Tab value="nextjs (Webpack)">
-
-### Next.js (Webpack)
-
-Если вы используете стандартный сборщик Webpack в Next.js, воспользуйтесь официальным анализатором сборки. Его можно запустить, установив переменную окружения во время сборки.
-
-```bash packageManager='npm'
-npm install -D @next/bundle-analyzer
-```
-
-```bash packageManager='yarn'
-yarn add -D @next/bundle-analyzer
-```
-
-```bash packageManager='pnpm'
-pnpm add -D @next/bundle-analyzer
-```
-
-```bash packageManager='bun'
-bun add -d @next/bundle-analyzer
-```
-
-```javascript fileName="next.config.js"
-const withBundleAnalyzer = require("@next/bundle-analyzer")({
-  enabled: process.env.ANALYZE === "true",
-});
-
-module.exports = withBundleAnalyzer({
-  // Ваш конфиг Next.js
-});
-```
-
-**Использование:**
-
-```bash
-ANALYZE=true npm run build
-```
-
- </Tab>
- <Tab value="Webpack (CRA / Angular / etc)">
-
-### Стандартный Webpack
-
-Для Create React App (ejected), Angular или пользовательских конфигураций Webpack используйте стандартный плагин `webpack-bundle-analyzer`.
-
-```bash packageManager='npm'
-npm install -D webpack-bundle-analyzer
-```
-
-```bash packageManager='yarn'
-yarn add -D webpack-bundle-analyzer
-```
-
-```bash packageManager='pnpm'
-pnpm add -D webpack-bundle-analyzer
-```
-
-```bash packageManager='bun'
-bun add -d webpack-bundle-analyzer
-```
-
-```typescript fileName="webpack.config.ts"
-import { BundleAnalyzerPlugin } from "webpack-bundle-analyzer";
-
-export default {
-  plugins: [
-    new BundleAnalyzerPlugin({
-      analyzerMode: "static",
-      reportFilename: "bundle-analyzer.html",
-      openAnalyzer: false,
-    }),
-  ],
-};
-```
-
- </Tab>
-</Tabs>
-
 ## Как это работает
 
 Intlayer использует **компонентный подход**. В отличие от глобальных JSON-файлов, ваш контент определяется рядом с вашими компонентами или внутри них. В процессе сборки Intlayer выполняет следующие действия:
@@ -189,59 +56,6 @@ Intlayer использует **компонентный подход**. В от
 - Если компонент не импортируется, его контент не включается в сборку (устранение мертвого кода — Dead Code Elimination).
 - Если компонент загружается лениво (lazy-loaded), его контент также загружается лениво.
 
-## Справочник по плагинам
-
-Оптимизация сборки Intlayer разделена на несколько дискретных плагинов, каждый из которых имеет свою единственную ответственность. Понимание того, что делает каждый плагин, предотвращает путаницу при их настройке.
-
-### Плагины Babel (`@intlayer/babel`)
-
-Они используются непосредственно в `babel.config.js` для сборок на базе Webpack (Next.js с Babel, CRA, пользовательский Webpack и т.д.).
-
-В таблице ниже они перечислены в требуемом порядке конвейера (в том же порядке, в котором они должны идти в `babel.config.js`):
-
-| Плагин                        | Что делает                                                                                                                              |
-| :---------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
-| `intlayerExtractBabelPlugin`  | Сканирует `.content.ts` файлы и записывает скомпилированные словари в `.intlayer/`                                                      |
-| `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 для определения того, какие поля используются.
-
-Каждый плагин Babel имеет соответствующий помощник параметров (options helper), который однократно считывает ваш `intlayer.config.ts` во время загрузки конфигурации и возвращает предварительно разрешенные (resolved) значения:
-
-| Помощник параметров          | Используется вместе с         |
-| :--------------------------- | :---------------------------- |
-| `getExtractPluginOptions()`  | `intlayerExtractBabelPlugin`  |
-| `getPurgePluginOptions()`    | `intlayerPurgeBabelPlugin`    |
-| `getMinifyPluginOptions()`   | `intlayerMinifyBabelPlugin`   |
-| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
-
-### Плагины 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` |
-
-### Плагин 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>
@@ -405,6 +219,59 @@ module.exports = {
  </Tab>
 </Tabs>
 
+## Справочник по плагинам
+
+Оптимизация сборки Intlayer разделена на несколько дискретных плагинов, каждый из которых имеет свою единственную ответственность. Понимание того, что делает каждый плагин, предотвращает путаницу при их настройке.
+
+### Плагины Babel (`@intlayer/babel`)
+
+Они используются непосредственно в `babel.config.js` для сборок на базе Webpack (Next.js с Babel, CRA, пользовательский Webpack и т.д.).
+
+В таблице ниже они перечислены в требуемом порядке конвейера (в том же порядке, в котором они должны идти в `babel.config.js`):
+
+| Плагин                        | Что делает                                                                                                                              |
+| :---------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
+| `intlayerExtractBabelPlugin`  | Сканирует `.content.ts` файлы и записывает скомпилированные словари в `.intlayer/`                                                      |
+| `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 для определения того, какие поля используются.
+
+Каждый плагин Babel имеет соответствующий помощник параметров (options helper), который однократно считывает ваш `intlayer.config.ts` во время загрузки конфигурации и возвращает предварительно разрешенные (resolved) значения:
+
+| Помощник параметров          | Используется вместе с         |
+| :--------------------------- | :---------------------------- |
+| `getExtractPluginOptions()`  | `intlayerExtractBabelPlugin`  |
+| `getPurgePluginOptions()`    | `intlayerPurgeBabelPlugin`    |
+| `getMinifyPluginOptions()`   | `intlayerMinifyBabelPlugin`   |
+| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
+
+### Плагины 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` |
+
+### Плагин 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 получает лишь готовые таблицы.
+
 ## Конфигурация
 
 Вы можете управлять тем, как Intlayer оптимизирует вашу сборку, через свойство `build` в вашем `intlayer.config.ts`.
@@ -650,3 +517,136 @@ const content = useDictionaryAsync({
 | **Сетевые запросы**         | 0 дополнительных запросов                  | 1 запрос на каждый ключ словаря        |
 | **Tree Shaking**            | На уровне компонентов                      | На уровне компонентов и локалей        |
 | **Лучший сценарий**         | UI-компоненты, небольшие приложения        | Крупный текст, многоязычность          |
+
+## Анализ вашей сборки
+
+Анализ вашей сборки (бандла) — это самый прямой способ выявить «тяжелые» JSON-файлы и возможности для разделения кода (code-splitting). Специализированные инструменты генерируют визуальное дерево (treemap) скомпилированного кода вашего приложения, что позволяет точно увидеть, какие библиотеки потребляют больше всего места.
+
+<Tabs>
+ <Tab value="vite">
+
+### Vite / Rollup
+
+Vite использует Rollup «под капотом». Плагин `rollup-plugin-visualizer` генерирует интерактивный HTML-файл, отображающий размер каждого модуля в вашем графе.
+
+```bash
+npm install -D rollup-plugin-visualizer
+```
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { visualizer } from "rollup-plugin-visualizer";
+
+export default defineConfig({
+  plugins: [
+    visualizer({
+      open: true, // Автоматически открывать отчет в браузере
+      filename: "stats.html",
+      gzipSize: true,
+      brotliSize: true,
+    }),
+  ],
+});
+```
+
+ </Tab>
+ <Tab value="nextjs (turbopack)">
+
+### Next.js (Turbopack)
+
+Для проектов, использующих App Router и Turbopack, Next.js предоставляет встроенный экспериментальный анализатор, который не требует установки дополнительных зависимостей.
+
+```bash packageManager='npm'
+npx next experimental-analyze
+```
+
+```bash packageManager='yarn'
+yarn next experimental-analyze
+```
+
+```bash packageManager='pnpm'
+pnpm next experimental-analyze
+```
+
+```bash packageManager='bun'
+bun next experimental-analyze
+```
+
+ </Tab>
+ <Tab value="nextjs (Webpack)">
+
+### Next.js (Webpack)
+
+Если вы используете стандартный сборщик Webpack в Next.js, воспользуйтесь официальным анализатором сборки. Его можно запустить, установив переменную окружения во время сборки.
+
+```bash packageManager='npm'
+npm install -D @next/bundle-analyzer
+```
+
+```bash packageManager='yarn'
+yarn add -D @next/bundle-analyzer
+```
+
+```bash packageManager='pnpm'
+pnpm add -D @next/bundle-analyzer
+```
+
+```bash packageManager='bun'
+bun add -d @next/bundle-analyzer
+```
+
+```javascript fileName="next.config.js"
+const withBundleAnalyzer = require("@next/bundle-analyzer")({
+  enabled: process.env.ANALYZE === "true",
+});
+
+module.exports = withBundleAnalyzer({
+  // Ваш конфиг Next.js
+});
+```
+
+**Использование:**
+
+```bash
+ANALYZE=true npm run build
+```
+
+ </Tab>
+ <Tab value="Webpack (CRA / Angular / etc)">
+
+### Стандартный Webpack
+
+Для Create React App (ejected), Angular или пользовательских конфигураций Webpack используйте стандартный плагин `webpack-bundle-analyzer`.
+
+```bash packageManager='npm'
+npm install -D webpack-bundle-analyzer
+```
+
+```bash packageManager='yarn'
+yarn add -D webpack-bundle-analyzer
+```
+
+```bash packageManager='pnpm'
+pnpm add -D webpack-bundle-analyzer
+```
+
+```bash packageManager='bun'
+bun add -d webpack-bundle-analyzer
+```
+
+```typescript fileName="webpack.config.ts"
+import { BundleAnalyzerPlugin } from "webpack-bundle-analyzer";
+
+export default {
+  plugins: [
+    new BundleAnalyzerPlugin({
+      analyzerMode: "static",
+      reportFilename: "bundle-analyzer.html",
+      openAnalyzer: false,
+    }),
+  ],
+};
+```
+
+ </Tab>
+</Tabs>

package/docs/ru/cli/doc-review.md

@@ -91,8 +91,6 @@ bun x intlayer doc review
 
 - **`--log`**: Режим только логирования. Не переводить с помощью ИИ; вместо этого логировать блоки, требующие внимания (с номерами строк и содержимым) для базовой и целевой локалей, чтобы помочь другому агенту сгенерировать переводы.
 
-I'm ready to assist you with the translation audit. However, I notice that:
-
 > Пример: `npx intlayer doc review --mode report`
 
 > Пример: `npx intlayer doc review --log`

package/docs/ru/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-08-22
+updatedAt: 2026-08-30
 title: Конфигурация (Configuration)
 description: Узнайте, как настроить Intlayer для вашего приложения. Разберитесь в различных параметрах и опциях, доступных для настройки Intlayer в соответствии с вашими потребностями.
 keywords:
@@ -1121,3 +1121,101 @@ Intlayer поддерживает несколько ИИ-провайдеров
 | Поле      | Описание                                | Тип                |
 | --------- | --------------------------------------- | ------------------ |
 | `plugins` | Список плагинов Intlayer для включения. | `IntlayerPlugin[]` |
+
+## Часто задаваемые вопросы
+
+<FAQ>
+
+<Question title="Где должен находиться файл intlayer.config.ts?">
+
+В корне вашего проекта, рядом с `package.json`. Intlayer также принимает `intlayer.config.js`, `intlayer.config.mjs`, `intlayer.config.cjs` и JSON, поэтому файл соответствует той модульной системе, которую использует ваш проект.
+
+</Question>
+
+<Question title="Насколько i18n увеличивает размер моего бандла?">
+
+Гораздо меньше, чем при подходе на основе пространств имён, потому что страница никогда не загружает каталог, который не отображает. Разметка, отрендеренная на сервере, разрешает свой контент на сервере, и компилятор во время сборки заменяет вызовы `useIntlayer` точными записями словаря, которые использует компонент, поэтому неиспользуемые ключи и неиспользуемые языки отбрасываются. [Динамические словари](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/dynamic_dictionaries/index.md) разделяют остальное по локалям. По сравнению с обычными альтернативами Intlayer сокращает размер бандла и страницы до 50%. См. [оптимизацию бандла](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/bundle_optimization.md) и [бенчмарк](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/benchmark/index.md).
+
+</Question>
+
+<Question title="Могу ли я мигрировать с `i18next`, `next-intl` или `react-i18next`, не переписывая свои компоненты?">
+
+Да, и есть два пути. Вы можете мигрировать контент постепенно с помощью [руководства по миграции с i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/migration_from_i18next_to_intlayer.md) или [руководства по миграции с next-intl](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/migration_from_next-intl_to_intlayer.md). Или вы можете полностью сохранить свой текущий API: [адаптеры совместимости](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/compat/index.md) предоставляют точно такой же API, как `i18next`, `react-i18next`, `next-intl`, `next-i18next`, `react-intl`, `use-intl`, `vue-i18n` и `Lingui`, но обслуживаемый словарями Intlayer, поэтому меняются импорты, а код компонентов - нет.
+
+</Question>
+
+<Question title="Могу ли я сохранить свои существующие файлы переводов JSON?">
+
+Да. [Плагин синхронизации JSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/plugins/sync-json.md) сохраняет ваши файлы `/messages/{locale}/{namespace}.json` как источник истины и генерирует из них словари Intlayer, в обоих направлениях. [Плагин синхронизации PO](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/plugins/sync-po.md) делает то же самое для каталогов gettext, а [файлы по локали](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/per_locale_file.md) позволяют разделить контент по языкам вместо группировки локалей в одном файле.
+
+</Question>
+
+<Question title="Должен ли я переносить свой контент ключ за ключом?">
+
+Нет. Запустите `npx intlayer extract`, и Intlayer прочитает ваши исходные файлы, извлечёт строки, видимые пользователю, и запишет файл `.content` рядом с каждым из них, так что вы просматриваете diff вместо копирования строк в каталог по одной. См. [команду extract](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/cli/extract.md).
+
+Для полностью автоматизированного конвейера [Компилятор Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/compiler.md) делает то же самое во время сборки на исходном коде JSX, TSX, Vue и Svelte, генерируя словари при каждом изменении, поэтому нет ключей, которые нужно поддерживать вручную. Он работает через статический анализ, поэтому строки, существующие только во время выполнения, остаются недоступными, и ему нужно несколько аннотаций, чтобы отличать текст, видимый пользователю, от логики приложения.
+
+</Question>
+
+<Question title="Какие инструменты для редактора и ИИ-агентов доступны?">
+
+Пять компонентов, все опциональные:
+
+- **[Расширение для VS Code](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/vs_code_extension.md)**: переход от ключа `useIntlayer` к файлу контента, который его объявляет, извлечение контента из компонента и запуск build, fill, test, push и pull из палитры команд или отдельной вкладки Intlayer.
+- **[LSP-сервер](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/lsp.md)**: та же осведомлённость в любом редакторе, который говорит на LSP, с переходом к определению, поиском всех ссылок, предпросмотром переведённого значения при наведении, автодополнением ключей и полей и предупреждением, когда ключ нигде не объявлен. Он также разрешает вызовы `i18next`, `react-i18next`, `next-intl` и `use-intl`, что помогает при миграции.
+- **[MCP-сервер](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/mcp_server.md)**: предоставляет документацию и CLI Intlayer для Cursor, VS Code, Claude Desktop, Claude Code и ChatGPT, чтобы ассистент отвечал по актуальной документации, а не гадал, и мог сам запускать команды вроде `intlayer fill`.
+- **[Навыки агентов](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/agent_skills.md)**: сфокусированные навыки, такие как `intlayer-config`, `intlayer-cli` и `intlayer-content`, плюс по одному на фреймворк, которые обучают агента вашей настройке маршрутизации и типам узлов контента.
+- **[Плагин ESLint](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/eslint.md)**: `no-raw-text` помечает жёстко закодированные строки, с дополнительными правилами для статических ключей словаря и неиспользуемого контента.
+
+</Question>
+
+<Question title="Как добавить новый язык в моё приложение?">
+
+Добавьте локаль в `internationalization.locales`, затем запустите `npx intlayer fill`, чтобы перевести существующий контент на неё. Сгенерированные типы обновляются одновременно, поэтому любой файл контента без новой локали становится ошибкой типа, а не молчаливым откатом.
+
+</Question>
+
+<Question title="Как убрать префикс локали из моих URL?">
+
+Установите `routing.mode`. Значение по умолчанию `"prefix-no-default"` даёт `/about` для локали по умолчанию и `/fr/about` для остальных. `"prefix-all"` добавляет префикс каждой локали. `"no-prefix"` полностью держит локаль вне пути и разрешает её из cookie, заголовка или домена. `"search-params"` помещает её в строку запроса как `/about?locale=fr`.
+
+</Question>
+
+<Question title="Могу ли я обслуживать каждый язык с его собственного домена?">
+
+Да. `routing.domains` сопоставляет локаль с именем хоста, например `{ fr: 'example.fr', en: 'example.com' }`. Домен идентифицирует локаль, поэтому префикс к пути не добавляется, а `getLocalizedUrl` возвращает абсолютный URL на правильном домене.
+
+</Question>
+
+<Question title="Как определяется язык пользователя?">
+
+Через `routing.storage`, который перечисляет источники для чтения по порядку, обычно URL, затем cookie, затем заголовок `Accept-Language`. Явный выбор пользователя сохраняется, поэтому он побеждает при следующем визите.
+
+</Question>
+
+<Question title="Что делает routing.enableProxy?">
+
+Она управляет прокси маршрутизации локали - middleware, который разрешает префиксы и редиректы. Если не задано, прокси работает, но серверы разработки и предпросмотра игнорируют сохранённую локаль как источник редиректа, что избегает переброски на язык, который вы не тестируете; в продакшене поведение такое, как если бы значение было `true`. Установите `false`, чтобы обрабатывать маршрутизацию локали самостоятельно.
+
+</Question>
+
+<Question title="В чём разница между importMode static, dynamic и fetch?">
+
+`"static"`, значение по умолчанию, импортирует словари статически, поэтому они упакованы и читаются синхронно. `"dynamic"` импортирует их через Suspense, поэтому локаль загружается только когда компонент её отображает, что и нужно для больших наборов контента. `"fetch"` получает их из API живой синхронизации и откатывается к `"dynamic"` при сбое. См. [оптимизацию бандла](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/bundle_optimization.md) и [динамические словари](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/dynamic_dictionaries/index.md).
+
+</Question>
+
+<Question title="Где указать ИИ-провайдера и API-ключ для автоматического перевода?">
+
+Либо в файле конфигурации, либо в командной строке с `--provider`, `--model` и `--api-key`. Ключ остаётся вашим: вызовы перевода идут с вашей машины или из вашего CI-раннера к выбранному вами провайдеру, поэтому ничего не проходит через третью сторону. См. [команду fill](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/cli/fill.md).
+
+</Question>
+
+<Question title="Нужно ли перезапускать dev-сервер после изменения конфигурации?">
+
+Обычно нет. Watcher Intlayer следит за самим `intlayer.config.ts`: при сохранении он перезагружает конфигурацию и снова подготавливает словари, поэтому добавление локали или смена режима маршрутизации подхватывается как изменение контента. Однако конфигурация может кэшироваться системами. Перезапуск вашего приложения может быть хорошим решением.
+
+</Question>
+
+</FAQ>

package/docs/ru/dictionary/content_file.md

@@ -367,15 +367,15 @@ Intlayer поддерживает различные типы содержимо
 
 **Пример:**
 
-```json
+```jsonc
 // Словарь для одной локали
 {
   "key": "about-page",
   "locale": "en",
   "content": {
     "title": "About Us", // Это становится узлом перевода для 'en'
-    "description": "Learn more about our company"
-  }
+    "description": "Learn more about our company",
+  },
 }
 ```
 
@@ -444,7 +444,7 @@ export default aboutPageMetaContent;
 
 **Примеры:**
 
-```json
+```jsonc
 // Включить для всех локалей
 {
   "autoFill": true

package/docs/ru/dictionary/markdown.md

@@ -104,7 +104,6 @@ Intlayer поддерживает форматированный текстов
 
   </Tab>
 
-  </Tab>
   <Tab label="Внешние файлы" value="external-files">
     Импортируйте файлы `.md` напрямую, используя функцию `file`.
 
@@ -140,7 +139,6 @@ Intlayer поддерживает форматированный текстов
 
   </Tab>
 
-  </Tab>
 </Tabs>
 
 ## Рендеринг Markdown

package/docs/ru/dictionary/plurial.md

@@ -33,11 +33,14 @@ To use plural content in Next.js Client Components, retrieve it via the `useIntl
 
 To use plural content in Angular components, retrieve it via the `useIntlayer` hook and call it with a count. Here's an example:
 
-## Когда использовать `plural` против `enu`
+## Когда использовать `plural` вместо `enu`
 
-To use plural content inside a React component, retrieve it via the `useIntlayer` hook and call it with a count. The active locale and the count are combined to pick the matching CLDR category.
+| Вариант использования                                                         | Хелпер   |
+| ----------------------------------------------------------------------------- | -------- |
+| Грамматические формы множественного числа для языка (яблоко / яблока / яблок) | `plural` |
+| Пользовательские числовые диапазоны (`<5`, `>=10`) или категории вне CLDR     | `enu`    |
 
-To use plural content in Next.js Client Components, retrieve it via the `useIntlayer` hook and call it with a count. Here's an example:
+Если вы ориентируетесь только на английский (где есть только `one` / `other`), подойдут оба варианта. Для языков с формами `few` / `many` / `two` выбирайте `plural`.
 
 ## Настройка контента во множественном числе
 

package/docs/ru/dictionary/translation.md

@@ -29,7 +29,6 @@ author: aymericzip
 
 With `react-intlayer`, you can use translations in React components. Here's an example:
 
-  </Tab>
   <Tab label="Next.js" value="nextjs">
 
 ```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
@@ -68,6 +67,7 @@ const MyComponent: Component = () => {
 export default MyComponent;
 ```
 
+  </Tab>
 ## Конфигурация локалей
 
 Для обеспечения правильной обработки переводов вы можете настроить поддерживаемые локали в файле `intlayer.config.ts`. Эта конфигурация позволяет определить языки, которые поддерживает ваше приложение: