@intlayer/docs 9.4.1 → 9.4.3

package/docs/ru/introduction.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-08-23
-updatedAt: 2025-08-23
+updatedAt: 2026-08-30
 title: Введение
 description: Узнайте, как работает Intlayer. Ознакомьтесь с этапами, которые использует Intlayer в вашем приложении. Узнайте, для чего предназначены различные пакеты.
 keywords:
@@ -93,7 +93,6 @@ export const MyComponent: FC = () => {
 По сравнению с основными решениями, такими как `next-intl` или `i18next`, Intlayer — это решение, в котором изначально присутствуют интегрированные оптимизации, такие как:
 
 <AccordionGroup>
-
 <Accordion header="Размер сборки (Bundle size)">
 
 Вместо того чтобы загружать массивные JSON-файлы на свои страницы, загружайте только необходимый контент. Intlayer помогает **сократить размер ваших сборок и страниц до 50%**.
@@ -204,3 +203,107 @@ Intlayer предлагает множество функций, адаптир
 Мы ценим силу open-source и разработки, управляемой сообществом. Если вы хотите предложить улучшения, добавить новое руководство или исправить какие-либо проблемы в нашей документации, смело отправляйте Pull Request или открывайте Issue в нашем [репозитории на GitHub](https://github.com/aymericzip/intlayer/blob/main/docs/docs).
 
 **Готовы переводить свое приложение быстрее и эффективнее?** Погрузитесь в нашу документацию, чтобы начать использовать Intlayer уже сегодня. Испытайте надежный и оптимизированный подход к интернационализации, который обеспечивает организованность вашего контента и повышает продуктивность вашей команды.
+
+## Часто задаваемые вопросы
+
+<FAQ>
+
+<Question title="Для чего используется Intlayer?">
+
+Intlayer - это библиотека интернационализации (i18n) для приложений на JavaScript и TypeScript. Вы объявляете контент компонента рядом с этим компонентом в файле `.content.ts`, Intlayer компилирует эти объявления в типизированные словари во время сборки, а ваши компоненты читают их через хук вроде `useIntlayer`. Она покрывает перевод, правила множественного числа, род, Markdown, маршрутизацию с учётом локали, SEO-метаданные, перевод с помощью ИИ и визуальный редактор для не-разработчиков.
+
+</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="Какие существуют решения для интернационализации приложения на JavaScript?">
+
+Область делится на три поколения:
+
+- **Библиотеки каталогов времени выполнения**: `i18next`, `react-i18next`, `next-i18next`, `vue-i18n`, `ngx-translate`. Сообщения живут в пространствах имён JSON, загружаемых во время выполнения. Зрелые и независимые от фреймворка, но нетипизированные и поставляемые целиком.
+- **Библиотеки сообщений времени компиляции**: `Lingui`, `Paraglide`, `react-intl` и `next-intl` с этапом извлечения. Лучшее поведение бандла и некоторая типизация, всё ещё централизованные каталоги.
+- **Библиотеки слоя контента**: `Intlayer`. Контент объявляется по компонентам и компилируется по компонентам, поэтому типизация, tree-shaking, инструменты и редактирование берутся из одного источника.
+
+См. [почему Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/interest_of_intlayer.md) для подробного сравнения и [бенчмарк](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/benchmark/index.md) для измеренных цифр по бандлу и производительности.
+
+</Question>
+
+<Question title="Какие фреймворки поддерживает Intlayer?">
+
+React, Next.js, Vite, TanStack Start, React Router, Vue, Nuxt, Svelte, SvelteKit, Angular, Solid, Preact, Lit, Astro с каждым островным фреймворком, React Native с Expo, Lynx, а на сервере - Express, Fastify, NestJS, Hono, Elysia и AdonisJS. У каждого есть собственное руководство в разделе [окружения](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/introduction.md).
+
+</Question>
+
+<Question title="Почему контент объявляется рядом с компонентом, а не в центральном файле JSON?">
+
+Три причины. Страница поставляет только те записи, которые отображают её компоненты, вместо целого пространства имён, что и сокращает размер бандла. Папку функции можно скопировать или удалить целиком, не выискивая в общем каталоге осиротевшие ключи. И LLM или агент, редактирующий компонент, видит его контент в той же папке, поэтому со-размещение делает работу с помощью ИИ надёжной. См. [как работает Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/how_works_intlayer.md).
+
+</Question>
+
+<Question title="Как автоматически перевести моё приложение с помощью ИИ?">
+
+Запустите `npx intlayer fill`. CLI обнаруживает недостающие переводы и заполняет их с помощью выбранной вами LLM, используя ваш собственный провайдер и API-ключ, поэтому вы платите ИИ-провайдеру напрямую. `--git-diff` ограничивает запуск контентом, изменённым в ветке, что делает его дешёвым в CI. См. [команду fill](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/cli/fill.md) и [интеграцию CI/CD](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/CI_CD.md).
+
+</Question>
+
+<Question title="Как найти недостающие переводы?">
+
+Запустите `npx intlayer test`. Она проваливается, когда объявленной локали не хватает контента, поэтому непереведённая строка никогда не попадёт в продакшен. [Расширение для VS Code](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/vs_code_extension.md) показывает те же ошибки inline, а [плагин ESLint](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/eslint.md) помечает жёстко закодированные строки своим правилом `no-raw-text`. См. [тестирование вашего контента](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/testing.md).
+
+</Question>
+
+<Question title="Нужно ли мне помещать локаль в URL?">
+
+Нет. `routing.mode` принимает `"prefix-no-default"` (по умолчанию, `/about` и `/fr/about`), `"prefix-all"`, `"no-prefix"` и `"search-params"`, а `routing.domains` сопоставляет каждую локаль с её собственным доменом. Какой бы ни была схема, `getMultilingualUrls` строит альтернативы `hreflang` для ваших метаданных и карты сайта. См. [справочник по конфигурации](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/configuration.md).
+
+</Question>
+
+<Question title="Как переводчики и редакторы контента могут работать, не касаясь кода?">
+
+[Визуальный редактор](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_visual_editor.md) работает на вашей собственной инфраструктуре и позволяет любому кликнуть на текст вашего работающего приложения, чтобы отредактировать его, записывая изменение обратно в кодовую базу. [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_CMS.md) выносит контент вовне, чтобы он мог меняться без развёртывания, при этом [живая синхронизация](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/cli/live.md) применяет обновления во время выполнения.
+
+</Question>
+
+<Question title="Является ли Intlayer бесплатным и с открытым исходным кодом?">
+
+Да. Intlayer имеет открытый исходный код по лицензии Apache 2.0, и библиотека, CLI, компилятор и визуальный редактор бесплатны в использовании, включая коммерческие проекты. Размещённая CMS - это необязательный платный сервис, и его также можно [разместить самостоятельно](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/self_hosting.md).
+
+</Question>
+
+</FAQ>

package/docs/ru/migration_from_i18next_to_intlayer.md

@@ -27,7 +27,6 @@ author: aymericzip
 ## Почему стоит перейти с i18next на Intlayer?
 
 <AccordionGroup>
-
 <Accordion header="Размер бандла">
 
 Вместо того чтобы загружать огромные JSON-файлы на ваших страницах, загружайте только необходимый контент. Intlayer помогает **сократить размер бандла и страниц до 50%**.
@@ -65,7 +64,6 @@ Intlayer также является **наиболее активно разв
 Будучи больше, чем просто решением i18n, Intlayer предоставляет **[визуальный редактор](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_visual_editor.md)** (self-hosted) и **[полноценную CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_CMS.md)**, чтобы помочь вам управлять мультиязычным контентом в **реальном времени**, делая сотрудничество с переводчиками, копирайтерами и другими членами команды бесшовным. Контент может храниться как локально, так и/или удаленно.
 
 </Accordion>
-
 </AccordionGroup>
 
 ---
@@ -103,15 +101,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > флаг `--interactive` не является обязательным. Используйте `intlayer-cli init`, если вы являетесь ИИ-агентом.

package/docs/ru/migration_from_next-i18next_to_intlayer.md

@@ -30,7 +30,6 @@ author: aymericzip
 ## Почему стоит перейти с next-i18next на Intlayer?
 
 <AccordionGroup>
-
 <Accordion header="Размер бандла">
 
 Вместо того чтобы загружать огромные JSON-файлы на ваших страницах, загружайте только необходимый контент. Intlayer помогает **сократить размер бандла и страниц до 50%**.
@@ -68,7 +67,6 @@ Intlayer также является **наиболее активно разв
 Будучи больше, чем просто решением i18n, Intlayer предоставляет **[визуальный редактор](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_visual_editor.md)** (self-hosted) и **[полноценную CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_CMS.md)**, чтобы помочь вам управлять мультиязычным контентом в **реальном времени**, делая сотрудничество с переводчиками, копирайтерами и другими членами команды бесшовным. Контент может храниться как локально, так и/или удаленно.
 
 </Accordion>
-
 </AccordionGroup>
 
 ---
@@ -106,15 +104,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > флаг `--interactive` не является обязательным. Используйте `intlayer-cli init`, если вы являетесь ИИ-агентом.

package/docs/ru/migration_from_next-intl_to_intlayer.md

@@ -28,7 +28,6 @@ author: aymericzip
 ## Почему стоит перейти с next-intl на Intlayer?
 
 <AccordionGroup>
-
 <Accordion header="Размер бандла">
 
 Вместо того чтобы загружать огромные JSON-файлы на ваших страницах, загружайте только необходимый контент. Intlayer помогает **сократить размер бандла и страниц до 50%**.
@@ -66,7 +65,6 @@ Intlayer также является **наиболее активно разв
 Будучи больше, чем просто решением i18n, Intlayer предоставляет **[визуальный редактор](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_visual_editor.md)** (self-hosted) и **[полноценную CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_CMS.md)**, чтобы помочь вам управлять мультиязычным контентом в **реальном времени**, делая сотрудничество с переводчиками, копирайтерами и другими членами команды бесшовным. Контент может храниться как локально, так и/или удаленно.
 
 </Accordion>
-
 </AccordionGroup>
 
 ---
@@ -102,15 +100,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > флаг `--interactive` не является обязательным. Используйте `intlayer-cli init`, если вы являетесь ИИ-агентом.

package/docs/ru/migration_from_nuxtjs_i18n_to_intlayer.md

@@ -29,7 +29,6 @@ author: aymericzip
 ## Почему стоит перейти с @nuxtjs/i18n на Intlayer?
 
 <AccordionGroup>
-
 <Accordion header="Размер бандла">
 
 Вместо того чтобы загружать огромные JSON-файлы на ваших страницах, загружайте только необходимый контент. Intlayer помогает **сократить размер бандла и страниц до 50%**.
@@ -67,7 +66,6 @@ Intlayer также является **наиболее активно разв
 Будучи больше, чем просто решением i18n, Intlayer предоставляет **[визуальный редактор](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_visual_editor.md)** (self-hosted) и **[полноценную CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_CMS.md)**, чтобы помочь вам управлять мультиязычным контентом в **реальном времени**, делая сотрудничество с переводчиками, копирайтерами и другими членами команды бесшовным. Контент может храниться как локально, так и/или удаленно.
 
 </Accordion>
-
 </AccordionGroup>
 
 ---
@@ -105,15 +103,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > флаг `--interactive` не является обязательным. Используйте `intlayer-cli init`, если вы являетесь ИИ-агентом.

package/docs/ru/migration_from_react-i18next_to_intlayer.md

@@ -29,7 +29,6 @@ author: aymericzip
 ## Почему стоит перейти с react-i18next / i18next на Intlayer?
 
 <AccordionGroup>
-
 <Accordion header="Размер бандла">
 
 Вместо того чтобы загружать огромные JSON-файлы на ваших страницах, загружайте только необходимый контент. Intlayer помогает **сократить размер бандла и страниц до 50%**.
@@ -67,7 +66,6 @@ Intlayer также является **наиболее активно разв
 Будучи больше, чем просто решением i18n, Intlayer предоставляет **[визуальный редактор](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_visual_editor.md)** (self-hosted) и **[полноценную CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_CMS.md)**, чтобы помочь вам управлять мультиязычным контентом в **реальном времени**, делая сотрудничество с переводчиками, копирайтерами и другими членами команды бесшовным. Контент может храниться как локально, так и/или удаленно.
 
 </Accordion>
-
 </AccordionGroup>
 
 ---
@@ -105,15 +103,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > флаг `--interactive` не является обязательным. Используйте `intlayer-cli init`, если вы являетесь ИИ-агентом.

package/docs/ru/migration_from_vue-i18n_to_intlayer.md

@@ -28,7 +28,6 @@ author: aymericzip
 ## Почему стоит перейти с vue-i18n на Intlayer?
 
 <AccordionGroup>
-
 <Accordion header="Размер бандла">
 
 Вместо того чтобы загружать огромные JSON-файлы на ваших страницах, загружайте только необходимый контент. Intlayer помогает **сократить размер бандла и страниц до 50%**.
@@ -66,7 +65,6 @@ Intlayer также является **наиболее активно разв
 Будучи больше, чем просто решением i18n, Intlayer предоставляет **[визуальный редактор](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_visual_editor.md)** (self-hosted) и **[полноценную CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_CMS.md)**, чтобы помочь вам управлять мультиязычным контентом в **реальном времени**, делая сотрудничество с переводчиками, копирайтерами и другими членами команды бесшовным. Контент может храниться как локально, так и/или удаленно.
 
 </Accordion>
-
 </AccordionGroup>
 
 ---
@@ -104,15 +102,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > флаг `--interactive` не является обязательным. Используйте `intlayer-cli init`, если вы являетесь ИИ-агентом.

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

@@ -71,7 +71,7 @@ export default defineConfig({
 
 Когда `intlayerPrune` анализирует кодовую базу и заполняет карту `pruneContext.dictionaryKeyToFieldRenameMap`, `intlayerMinify` также переименовывает имена полей контента в короткие алиасы. Например:
 
-```json
+```jsonc
 // до
 { "key": "myDict", "content": { "title": "Hello", "description": "World" } }