@intlayer/docs 9.5.6 → 9.5.8

package/blog/ru/lingui_vs_intlayer.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-09-13
-updatedAt: 2026-09-13
+updatedAt: 2026-09-22
 title: "Lingui против Intlayer: бенчмарк и сравнение 2026"
 description: "Две библиотеки интернационализации на базе компилятора, протестированные на Next.js и TanStack Start. Размер бандла, утечка контента, размер компонентов, гидратация, отзывчивость при смене языка и опыт разработки."
 keywords:
@@ -24,6 +24,8 @@ author: aymericzip
 
 # Lingui против Intlayer | Бенчмарк интернационализации (i18n) для React и Next.js
 
+![JavaScript i18n library ecosystem](https://github.com/aymericzip/intlayer/blob/main/docs/assets/cloud_i18n_logo.webp?raw=true)
+
 Lingui и Intlayer - единственные две библиотеки в этом сравнительном исследовании, которые опираются на **компилятор**, а не на обычный рантайм. Lingui извлекает сообщения из макросов во время сборки и компилирует каталоги под каждую локаль. Intlayer компилирует словари на уровне компонентов и применяет tree-shaking отдельно для каждого языка. В теории их показатели должны быть близки. Цифры показывают, в чем они существенно расходятся.
 
 Данные получены с помощью [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom) - открытого набора тестов, который собирает одно и то же приложение с каждой библиотекой и замеряет то, что браузер реально скачивает и исполняет.
@@ -96,6 +98,10 @@ Lingui и Intlayer - единственные две библиотеки в э
 
 ### Результаты на Next.js
 
+Выберите интересующие вас метрики и библиотеки:
+
+<I18nBenchmark framework="nextjs" vertical/>
+
 | Библиотека          | Стратегия      | Lib size (gz) | Page JS ср. (gz) | Утечка языка | Утечка страниц | Компонент ср. (gz) | E2E-реактивность | Гидратация |
 | ------------------- | -------------- | ------------: | ---------------: | -----------: | -------------: | -----------------: | ---------------: | ---------: |
 | **база** (без i18n) | -              |        0,0 КБ |         141,0 КБ |         0,0% |           0,0% |             0,9 КБ |          13,4 мс |    11,8 мс |
@@ -114,6 +120,15 @@ Lingui и Intlayer - единственные две библиотеки в э
 - **Утечка оригинального текста.** Даже в наиболее продуманных схемах **от 3% до 15% английских строк попадают на страницы на французском языке**. Макросы Lingui встраивают исходную строку для подстраховки в итоговый бандл. Intlayer разрешает фолбеки на этапе сборки и доставляет клиенту только целевой язык.
 - **Взрывной рост размера компонентов в `scoped-dynamic`.** Каждый изолированный компонент весит в среднем **152,6 КБ**, поскольку через цепочку импортов в него попадают каталоги других маршрутов. Тот же компонент на `useIntlayer()` занимает всего **6,9 КБ**.
 
+<ClickToOpenIframe
+src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-nextjs.md"
+width="100%"
+height="600px"
+style="border:none;"
+/>
+
+> Полная таблица, каждая библиотека и стратегия в [отчете о бенчмарке Next.js](https://intlayer.org/ru/doc/benchmark/nextjs).
+
 ### Результаты на TanStack Start
 
 | Библиотека                   | Стратегия      | Lib size (gz) | Page JS ср. (gz) | Утечка языка | Утечка страниц | Компонент ср. (gz) | E2E-реактивность | Гидратация |
@@ -135,8 +150,19 @@ Lingui и Intlayer - единственные две библиотеки в э
 - **Строка `static` у Intlayer сразу обеспечивает 0% утечки страниц**, так как в бандл включаются исключительно словари, импортированные задействованными на странице компонентами. А параметр `importMode: 'dynamic'` устраняет и языковую утечку.
 - **`@intlayer/lingui`** сохраняет синтаксис макросов Lingui, связывая их со словарями Intlayer. Это решение жертвует небольшим объемом на страницу (137 КБ из-за присутствия макро-рантайма), взамен давая облегченные компоненты (12,8 КБ) и быструю гидратацию. Прекрасный вариант для плавного перехода.
 
+<ClickToOpenIframe
+src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-tanstack.md"
+width="100%"
+height="600px"
+style="border:none;"
+/>
+
+> Полная таблица в [отчете о бенчмарке TanStack Start](https://intlayer.org/ru/doc/benchmark/tanstack).
+
 ## В чем фундаментальная причина? Два компилятора, две единицы деления
 
+![The Intlayer compiler extracts content from components](https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.webp?raw=true)
+
 Обе библиотеки компилируют код, но принципиально отличается **объект компиляции**.
 
 **Lingui компилирует каталоги.** Макросы в коде извлекаются в единый файл `.po` на язык, а затем компилируются в модуль JS на язык. Главная единица деления - **локаль**. Чтобы разделить данные глубже (по маршрутам или компонентам), вам придется заводить отдельные каталоги, прописывать правила в `lingui.config.ts` и вручную настраивать их загрузку. Экземпляр `I18n` глобален, и каждый `useLingui()` подключает компонент ко всему его содержимому.
@@ -176,7 +202,9 @@ Lingui и Intlayer - единственные две библиотеки в э
             └── about.content.ts
 ```
 
-Именно поэтому архитектура `scoped-dynamic` формируется в Intlayer автоматически на этапе сборки, тогда как в Lingui это требует масштабной ручной настройки.
+Именно поэтому архитектура `scoped-dynamic` формируется в Intlayer автоматически на этапе сборки, тогда как в Lingui это требует масштабной ручной настройки. Разрыв увеличивается сразу по двум осям, страницы и локали:
+
+![Theoretical content leakage by architecture](https://github.com/aymericzip/intlayer/blob/main/docs/assets/theorical_content_leakage.webp?raw=true)
 
 > Чтобы повторить показатели строки `dynamic`, активируйте `dictionary.importMode: 'dynamic'` в `intlayer.config.ts`. Подробнее в [документации по оптимизации бандла](https://intlayer.org/ru/doc/concept/bundle-optimization).
 
@@ -184,7 +212,8 @@ Lingui и Intlayer - единственные две библиотеки в э
 
 ### Настройка
 
-**Lingui**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="Lingui" value="lingui">
 
 ```ts fileName="lingui.config.ts"
 import { defineConfig } from "@lingui/cli";
@@ -215,7 +244,8 @@ export const loadCatalog = async (locale: string) => {
 
 Затем в сборщик добавляется плагин `@lingui/babel-plugin-lingui-macro` (или `@lingui/swc-plugin`), после правок выполняется `lingui extract`, перед сборкой - `lingui compile`, а приложение оборачивается в `<I18nProvider i18n={i18n}>`.
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```ts fileName="intlayer.config.ts"
 import { type IntlayerConfig, Locales } from "intlayer";
@@ -232,9 +262,12 @@ export default config;
 
 Добавьте плагин `intlayer()` в `vite.config.ts` (или `withIntlayer()` в `next.config.ts`) и оберните дерево компонентов в `<IntlayerProvider>`. Никаких ручных команд извлечения или сборки: словари компилируются автоматически бандлером.
 
+</Tab>
+</Tabs>
 ### Компоненты
 
-**Lingui**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="Lingui" value="lingui">
 
 ```tsx fileName="src/components/Counter.tsx"
 import { useState } from "react";
@@ -258,7 +291,8 @@ export const Counter = () => {
 
 Английский текст пишется прямо в компоненте; перевод на французский хранится в `src/locales/fr/messages.po` под сгенерированным хеш-идентификатором после выполнения `lingui extract`. Если забыть запустить команду извлечения или сборки, на экране незаметно останется английский текст.
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```ts fileName="src/components/Counter/index.content.ts"
 import { t, type Dictionary } from "intlayer";
@@ -297,11 +331,14 @@ export const Counter = () => {
 
 Оба языка находятся в одном файле рядом с компонентом. Отсутствие перевода для `fr` приведет к ошибке сборщика, а опечатка в имени ключа будет немедленно подсвечена TypeScript.
 
+</Tab>
+</Tabs>
 ### Вне компонентов React
 
 Метаданные, функции загрузки данных (loaders), серверные функции: в любом контексте без дерева React.
 
-**Lingui**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="Lingui" value="lingui">
 
 ```ts fileName="src/routes/$locale/about.tsx"
 import { setupI18n } from "@lingui/core";
@@ -324,7 +361,8 @@ export const loader = async ({ params }: { params: { locale: string } }) => {
 
 Создание нового экземпляра `I18n` на каждый вызов, ручной импорт конкретного каталога и использование `msg` + `i18n._()` вместо привычного `t`. Как отмечается в [примечаниях к бенчмарку](https://github.com/intlayer-org/benchmark-bloom/blob/main/report/NOTE.md), постоянный выбор между `t`, `` t` ` ``, `i18n.t()`, `msg` или `<Trans>` часто сбивает с толку.
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```ts fileName="src/routes/$locale/about.tsx"
 import { getIntlayer } from "intlayer";
@@ -336,6 +374,9 @@ export const loader = async ({ params }: { params: { locale: string } }) => {
 };
 ```
 
+</Tab>
+</Tabs>
+
 ## Использование макросов Lingui со словарями Intlayer
 
 `@intlayer/lingui` работает как прозрачный адаптер для `@lingui/core` и `@lingui/react`. Макросы компилируются в прежнем режиме; генерируемые вызовы `i18n._()` берут данные из словарей Intlayer, а плагины синхронизации сохраняют файлы `.po` в качестве источника данных. Формы множественного числа и условия ICU отображаются абсолютно идентично.
@@ -353,16 +394,82 @@ export default defineConfig({
 
 ## Что выбрать для вашего проекта?
 
-- **Выбирайте Lingui**, если вам необходим синтаксис **ICU MessageFormat** с типизированными макросами, переводчики работают через файлы **`.po`** в сформированном процессе TMS, вам удобнее писать текст прямо в JSX, а команда готова поддерживать процесс извлечения, сборки и деления каталогов. При правильной настройке ленивой загрузки размер итоговой страницы крайне конкурентен.
-- **Выбирайте Intlayer**, если вам нужны **изолированный контент на уровне компонентов**, **строгая типизация TypeScript**, **контроль отсутствующих ключей на этапе сборки**, **автоматический tree-shaking и ленивая загрузка без конфигурации**, легковесные компоненты, мгновенная смена локалей и встроенные инструменты редактирования (Визуальный редактор, CMS, перевод через ИИ, сервер MCP). Идеально подходит для модульных систем и дизайн-систем.
-- **Выбирайте `@intlayer/lingui`**, если у вас уже есть кодовая база на Lingui и вы хотите постепенно перейти на архитектуру словарей Intlayer, не переписывая макросы.
+<AccordionGroup>
+<Accordion header="Выбрать Lingui">
+
+Вам нужен **ICU MessageFormat** с типизированными макросами, ваши переводчики работают в **`.po`** с существующим пайплайном TMS, вы предпочитаете исходные строки инлайн в JSX, и вашей команде удобно управлять извлечением, компиляцией и разделением каталогов. Его JS на страницу вполне конкурентоспособен после настройки lazy loading.
+
+</Accordion>
+<Accordion header="Выбрать Intlayer">
+
+Вам нужен **контент с областью видимости на уровне компонентов**, **строгий TypeScript**, **ошибки отсутствующих ключей во время сборки**, **tree-shaking и lazy loading без усилий**, компактные компоненты, быстрая гидратация, мгновенное переключение локалей и встроенные инструменты редактирования ([Визуальный редактор](https://intlayer.org/ru/doc/concept/editor), [CMS](https://intlayer.org/ru/doc/concept/cms), [ИИ-перевод](https://intlayer.org/ru/doc/concept/auto-fill), [MCP-сервер](https://intlayer.org/ru/doc/mcp-server)). Особенно актуально для крупных модульных кодовых баз и дизайн-систем.
+
+</Accordion>
+<Accordion header="Выбрать @intlayer/lingui">
+
+Вы уже используете Lingui и хотите постепенно перейти на словари Intlayer, не трогая макросы. Ваши каталоги `.po` остаются источником истины благодаря [плагину синхронизации PO](https://intlayer.org/ru/doc/compatibility/lingui). Измерено бок о бок в [Lingui vs @intlayer/lingui](https://intlayer.org/ru/blog/lingui-vs-intlayer-lingui).
+
+</Accordion>
+</AccordionGroup>
+
+## FAQ
+
+<FAQ>
+
+<Question title="Lingui тоже компилирует. Почему результат настолько разный?">
+
+Потому что единица компиляции различается. Lingui компилирует **один каталог на локаль**: всё, что ниже этого (каталоги по маршрутам, lazy loading, исключение fallback из бандла), требует ручной конфигурации. Intlayer компилирует **один словарь на компонент**, поэтому разделение по маршрутам происходит автоматически во время сборки. Вот почему изолированно скомпилированный компонент Lingui весит 58-153 KB против 6-8 KB у Intlayer.
+
+</Question>
+
+<Question title="Почему утечка локалей никогда не достигает 0% с Lingui?">
+
+Макросы сохраняют исходное сообщение доступным в рантайме в качестве фоллбэка, поэтому английская строка отправляется вместе с переводом. Бенчмарк фиксирует **3-15% строк `en` внутри страниц `fr`** в каждой оптимизированной конфигурации. Intlayer разрешает фоллбэки во время сборки и отправляет только активную локаль.
+
+</Question>
+
+<Question title="Действительно ли JavaScript на страницу у Lingui конкурентоспособен?">
+
+Да, а на TanStack Start он даже чуть впереди: 115.2 KB в режиме `dynamic` против 118.6 KB у Intlayer. Скомпилированные каталоги с хэшированными ID компактны. Однако цена проявляется в других аспектах: гидратация за 28-34 мс против 11-14 мс и переключение локали за **42 мс** в конфигурации `scoped-dynamic`.
+
+</Question>
+
+<Question title="Нужно ли отказываться от макросов для миграции?">
+
+Нет. `@intlayer/lingui` сохраняет компиляцию `` t`...` ``, `<Trans>`, `msg`, `plural`, `select` и `selectOrdinal` как раньше; меняется только то, относительно чего резолвит `i18n._()`. Сохраните `@lingui/babel-plugin-lingui-macro` или `@lingui/swc-plugin` в сборке. См. [документацию по совместимости с Lingui](https://intlayer.org/ru/doc/compatibility/lingui).
+
+</Question>
+
+<Question title="Что насчет этапов извлечения и компиляции?">
+
+Они остаются для макросов и исчезают для собственного контента Intlayer. Словари `.content.ts` собираются при запуске бандлера без отдельного шага CLI, а [`intlayer test`](https://intlayer.org/ru/doc/concept/cli) прерывает CI при отсутствии ключа вместо тихого отката к исходной строке.
+
+</Question>
+
+</FAQ>
 
 ## Похожие сравнения
 
-- [next-intl против Intlayer](https://intlayer.org/ru/blog/next-intl-vs-intlayer) (в рамках того же бенчмарка)
-- [i18next против Intlayer](https://intlayer.org/ru/blog/i18next-vs-intlayer) (в рамках того же бенчмарка)
-- [vue-i18n против Intlayer](https://intlayer.org/ru/blog/vue-i18n-vs-intlayer-benchmark) (в рамках того же бенчмарка)
-- [Компилятор против декларативной i18n](https://intlayer.org/ru/blog/compiler-vs-declarative-i18n)
+Тот же бенчмарк, другие библиотеки:
+
+- [next-intl vs Intlayer](https://intlayer.org/ru/blog/next-intl-vs-intlayer)
+- [i18next vs Intlayer](https://intlayer.org/ru/blog/i18next-vs-intlayer)
+- [vue-i18n vs Intlayer benchmark](https://intlayer.org/ru/blog/vue-i18n-vs-intlayer-benchmark)
+- [next-i18next vs next-intl vs Intlayer](https://intlayer.org/ru/blog/next-i18next-vs-next-intl-vs-intlayer)
+- [react-i18next vs react-intl vs Intlayer](https://intlayer.org/ru/blog/react-i18next-vs-react-intl-vs-intlayer)
+
+Подробнее:
+
+- [Lingui vs @intlayer/lingui](https://intlayer.org/ru/blog/lingui-vs-intlayer-lingui), адаптер измерен на том же приложении
+- [Compiler-driven vs declarative i18n](https://intlayer.org/ru/blog/compiler-vs-declarative-i18n)
+- [Per-component vs centralized i18n](https://intlayer.org/ru/blog/per-component-vs-centralized-i18n)
+- [ICU message format explained](https://intlayer.org/ru/blog/icu-message-format)
+
+Справочная документация:
+
+- [Отчет о бенчмарке Next.js](https://intlayer.org/ru/doc/benchmark/nextjs) и [отчет о бенчмарке TanStack Start](https://intlayer.org/ru/doc/benchmark/tanstack)
+- [Compat adapter: Lingui](https://intlayer.org/ru/doc/compatibility/lingui)
+- [Оптимизация бандла](https://intlayer.org/ru/doc/concept/bundle-optimization) и [компилятор Intlayer](https://intlayer.org/ru/doc/compiler)
 
 ## Звезды на GitHub
 

package/blog/ru/next-intl_vs_intlayer-next-intl.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-09-13
-updatedAt: 2026-09-13
+updatedAt: 2026-09-22
 title: "next-intl vs @intlayer/next-intl: Один и тот же API, разный Bundle"
 description: Что меняется, когда импорты next-intl приложения Next.js обслуживаются адаптером совместимости @intlayer/next-intl. Размер bundle, утечки, размер компонента и гидратация, измеренные на одном коде, плюс то, что адаптер сохраняет, игнорирует и не может заменить.
 keywords:
@@ -26,6 +26,8 @@ author: aymericzip
 
 # next-intl VS @intlayer/next-intl | Один и тот же API, разный Bundle
 
+![next-intl VS Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18next-next-intl-intlayer.webp?raw=true)
+
 `@intlayer/next-intl` - это адаптер совместимости: он предоставляет API `next-intl` (`useTranslations`, `getTranslations`, `useLocale`, `t.rich()`, ICU plurals, `NextIntlClientProvider`...) и обслуживает его из словарей, скомпилированных Intlayer. Код приложения не меняется. Меняется bundle.
 
 Эта статья сравнивает оба варианта на одном Next.js приложении, собранном один раз с `next-intl` и один раз с адаптером. Цифры взяты из [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom), open-source набора инструментов, который записывает, что на самом деле загружает браузер. Если вам нужно сравнение `next-intl` и Intlayer как библиотек, прочитайте [next-intl vs Intlayer](https://intlayer.org/ru/blog/next-intl-vs-intlayer). Здесь речь идёт о том, что меняется в адаптере, когда вы оставляете компоненты как они есть.
@@ -109,6 +111,10 @@ const AboutPage = () => {
 
 ### Результаты на Next.js
 
+Выберите интересующие вас метрики и библиотеки:
+
+<I18nBenchmark framework="nextjs" vertical/>
+
 | Setup                     | Strategy       | Lib size (gz) | Page JS avg (gz) | Locale leak | Page leak | Component avg (gz) | E2E reactivity |   Hydration |
 | ------------------------- | -------------- | ------------: | ---------------: | ----------: | --------: | -----------------: | -------------: | ----------: |
 | **base** (no i18n)        | -              |        0.0 KB |         141.0 KB |        0.0% |      0.0% |             0.9 KB |        13.4 ms |     11.8 ms |
@@ -129,6 +135,15 @@ const AboutPage = () => {
 - **Гидратация на 2 мс быстрее** (12.8 против 14.7 мс): нет необходимости десериализовать объект сообщения из RSC payload перед тем, как React может выполнить гидратацию.
 - **Адаптер не является нативным runtime.** `next-intlayer` занимает **141.3 KB**, +0.3 KB относительно базового приложения, с runtime 5.5 KB. Адаптер предоставляет API поверхность `next-intl` (`useFormatter`, `t.rich`, ICU resolver) поверх ядра Intlayer, отсюда 8.0 KB и +6 KB на страницу. Это мост, а не пункт назначения.
 
+<ClickToOpenIframe
+src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-nextjs.md"
+width="100%"
+height="600px"
+style="border:none;"
+/>
+
+> Полная таблица, каждая библиотека и стратегия в [отчете о бенчмарке Next.js](https://intlayer.org/ru/doc/benchmark/nextjs).
+
 ### Результаты на TanStack Start (`use-intl`)
 
 `use-intl` - это framework-агностическое ядро `next-intl`. Его адаптер, `@intlayer/use-intl`, следует той же архитектуре с Vite плагином (`@intlayer/use-intl/plugin`).
@@ -152,11 +167,24 @@ const AboutPage = () => {
 - **Переключение локалей работает быстрее.** Оптимизированные настройки `use-intl` занимают **13-21 ms** для обновления `html[lang]`; адаптер занимает **4-9 ms**. Меньше компонентов перерисовывается, и ничего не переходит из дерева сообщений.
 - **`static` сохраняет каждую локаль.** Строка `static` адаптера показывает утечку локалей на 49.7%, как и native Intlayer в режиме `static`: все локали объединены, но используются только словари страницы. Одна строка конфига (`importMode: 'dynamic'`) это убирает.
 
+<ClickToOpenIframe
+src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-tanstack.md"
+width="100%"
+height="600px"
+style="border:none;"
+/>
+
+> Полная таблица в [отчете о бенчмарке TanStack Start](https://intlayer.org/ru/doc/benchmark/tanstack).
+
 ## Почему цифры меняются
 
+![The Intlayer compiler extracts content from components](https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.webp?raw=true)
+
 Ничего в компоненте не изменилось, поэтому прирост производительности полностью зависит от того, к чему привязана `useTranslations`.
 
-**With `next-intl`**, the binding is the provider. `NextIntlClientProvider` receives the whole `messages` object for the locale; every `useTranslations("about")` reads from it. The bundler sees one component importing one hook that reads one context, and cannot know that only the `about` branch is used. The routes below all share the same message object, so the page-leak column reads ~90% until you split the file yourself.
+**With `next-intl`**, the binding is the provider. `NextIntlClientProvider` receives the whole `messages` object for the locale; every `useTranslations("about")` reads from it. The bundler sees one component importing one hook that reads one context, and cannot know that only the `about` branch is used. The routes below all share the same message object, so the page-leak column reads ~90% until you split the file yourself, и потери растут сразу по двум осям, страницы и локали:
+
+![Theoretical content leakage by architecture](https://github.com/aymericzip/intlayer/blob/main/docs/assets/theorical_content_leakage.webp?raw=true)
 
 ```bash
 .
@@ -273,32 +301,113 @@ export default withIntlayer(nextConfig);
 
 ### Что вы получаете сверх оптимизации размера
 
-- **Типизированные ключи.** `useTranslations("about")` типизирована против скомпилированного словаря `about`. `t("does.not.exist")` — это ошибка TypeScript, а не fallback во время выполнения.
+- **Типизированные ключи.** `useTranslations("about")` типизирована против скомпилированного словаря `about`. `t("does.not.exist")`, это ошибка TypeScript, а не fallback во время выполнения.
 - **`npx intlayer test`** блокирует CI, когда в какой-то локали отсутствует ключ. **`npx intlayer fill`** переводит отсутствующие ключи с помощью выбранного провайдера (OpenAI, Anthropic, Mistral, Gemini...) используя ваш собственный ключ и записывает результат обратно в `messages/{locale}.json`.
 - **Visual Editor и CMS** работают с одними и теми же словарями, поэтому не-разработчики могут редактировать `messages/fr.json` через UI, и файл обновляется.
 - **Постепенный переход на `.content.ts`.** Любой компонент может переключиться с `useTranslations("about")` на `useIntlayer("about")` с co-located content файлом, по одному за раз. JSON и `.content.ts` словари сосуществуют и объединяются.
 
 ## Ограничения, которые нужно знать перед началом
 
-- **Routing config переходит в `intlayer.config.ts`.** `createNavigation(routing)` и `createMiddleware(routing)` сохраняют свою сигнатуру, но игнорируют аргумент: локали, локаль по умолчанию и стратегия префикса поступают из конфига Intlayer's `routing`. Если вы используете локализованные `pathnames` от `next-intl` (`/about` → `/a-propos`), адаптер их не интерполирует; `intlayer.routing.rewrite` покрывает этот случай, но это отдельное изменение.
-- **`useTranslations()` без namespace не привязан.** Этап оптимизации требует статический namespace, чтобы знать, какой dictionary импортировать. Прямой вызов все еще работает через registry во время выполнения, который ссылается на каждый dictionary, что точно утечка, которую вы пытались избежать. Передайте namespace.
-- **Адаптер не бесплатен.** 8.0 KB runtime против 5.5 KB для `next-intlayer` и +6-7 KB на страницу по сравнению с native build. Это цена за API surface `next-intl`. Если вы дошли до точки, где каждый компонент был перемещен на `useIntlayer`, отказывайтесь от адаптера.
-- **`messages`, `timeZone`, `now` на провайдере игнорируются.** Форматеры поддерживаются нативным `Intl` и только locale влияет на их output; если вы полагаетесь на forced time zone или fixed `now` для hydration-stable дат, обработайте это на call site.
+<AccordionGroup>
+<Accordion header="Конфигурация маршрутизации переносится в intlayer.config.ts">
+
+`createNavigation(routing)` и `createMiddleware(routing)` сохраняют сигнатуру, но игнорируют аргумент: локали, локаль по умолчанию и стратегия префиксов берутся из конфигурации `routing` Intlayer. Если вы используете локализованные `pathnames` из `next-intl` (`/about` в `/a-propos`), адаптер их не интерполирует; `routing.rewrite` Intlayer покрывает этот случай, но это отдельное изменение.
+
+</Accordion>
+<Accordion header="useTranslations() без пространства имен не связывается">
+
+Фазе оптимизации требуется статическое пространство имен, чтобы знать, какой словарь импортировать. Вызов без namespace все еще работает через реестр рантайма, ссылающийся на каждый словарь, что как раз и является той утечкой, которую вы пытались устранить. Передавайте namespace.
+
+</Accordion>
+<Accordion header="Адаптер не бесплатен">
+
+8.0 KB рантайма против 5.5 KB у `next-intlayer`, и +6-7 KB на страницу по сравнению с нативной сборкой. Это плата за API `next-intl`. Когда все компоненты будут переведены на `useIntlayer`, удалите адаптер.
+
+</Accordion>
+<Accordion header="messages, timeZone и now в провайдере игнорируются">
+
+Форматтеры основаны на нативном `Intl`, и только локаль влияет на вывод. Если вам нужен принудительный часовой пояс или фиксированное `now` для стабильной гидратации дат, управляйте этим в месте вызова. См. [форматирование дат, времени и чисел](https://intlayer.org/ru/blog/date-time-number-formatting-locales).
+
+</Accordion>
+</AccordionGroup>
 
 ## Когда использовать что?
 
-- **Оставайтесь на `next-intl`** если ваше приложение небольшое, bundle не вызывает беспокойства, и ваша команда комфортно владеет namespaces и `pick()` на каждой странице.
-- **Используйте `@intlayer/next-intl`**, если вы сейчас работаете с `next-intl` и хотите получить преимущества в размере bundle, устранение утечек и гидрации, типизированные ключи и инструменты CLI / CMS без переписывания. Это рекомендуемая точка входа для любого существующего `next-intl` codebase.
-- **Перейдите на native (`next-intlayer`)** для новых проектов или после того, как adapter выполнит свою работу. Это самый легкий из трех (5.5 KB, +0.3 KB за страницу) и разблокирует синхронные server components, `.content.ts` файлы per-component и полный набор функций.
+<AccordionGroup>
+<Accordion header="Остаться на next-intl">
+
+Ваше приложение небольшое, размер бандла вас не беспокоит, и вашей команде удобно вручную управлять пространствами имен и `pick()` на каждой странице.
+
+</Accordion>
+<Accordion header="Использовать @intlayer/next-intl">
+
+Вы уже используете `next-intl` сегодня и хотите получить преимущества в размере бандла, отсутствии утечек, быстрой гидратации, типизированных ключах и инструментах CLI / CMS без переписывания кода. Это рекомендуемая точка входа для любой существующей кодовой базы `next-intl`.
+
+</Accordion>
+<Accordion header="Перейти на нативный next-intlayer">
+
+Для новых проектов или когда адаптер выполнил свою задачу. Это самый легкий из трех вариантов (5.5 KB, +0.3 KB на страницу), который открывает синхронные серверные компоненты, файлы `.content.ts` для каждого компонента и полный набор функций. Начните с [Intlayer с Next.js](https://intlayer.org/ru/doc/environment/nextjs).
+
+</Accordion>
+</AccordionGroup>
+
+## FAQ
+
+<FAQ>
+
+<Question title="Действительно ли код моего приложения остается нетронутым?">
+
+В Next.js да для компонентов: сборка бенчмарка изменила только `next.config.ts` и `intlayer.config.ts`. `getRequestConfig` в `src/i18n.ts`, проп `messages` в провайдере и вызовы `pick()` становятся мертвым кодом, который затем можно удалить.
+
+</Question>
+
+<Question title="Что происходит с сообщениями ICU?">
+
+Они продолжают работать. `t("key", { count })`, `t.rich()`, `t.markup()`, `select`, `selectordinal`, `#` и `{ts, date, long}` обрабатываются резолвером ICU в Intlayer. См. [формат сообщений ICU](https://intlayer.org/ru/blog/icu-message-format).
+
+</Question>
+
+<Question title="Почему адаптер тяжелее нативного next-intlayer?">
+
+Он несет на себе API `next-intl` поверх ядра Intlayer: `useFormatter`, `t.rich`, резолвер ICU, хелперы навигации. Это 8.0 KB против 5.5 KB и +6 KB на страницу. Это мост, а не конечная цель.
+
+</Question>
+
+<Question title="Могу ли я мигрировать компонент за компонентом?">
+
+Да. Любой компонент может перейти с `useTranslations("about")` на `useIntlayer("about")` с рядом лежащим `.content.ts`. Словари JSON и `.content.ts` сосуществуют и объединяются.
+
+</Question>
+
+<Question title="Работают ли локализованные пути (pathnames)?">
+
+Не через `pathnames` из `next-intl`: адаптер принимает их для типизации, но не интерполирует. Используйте вместо этого `routing.rewrite` от Intlayer.
+
+</Question>
+
+</FAQ>
 
 ## Связанные сравнения
 
-- [next-intl vs Intlayer](https://intlayer.org/blog/next-intl-vs-intlayer) (библиотеки, одинаковый benchmark)
-- [i18next vs @intlayer/i18next](https://intlayer.org/blog/i18next-vs-intlayer-i18next) (одна серия adapter)
-- [Lingui vs @intlayer/lingui](https://intlayer.org/blog/lingui-vs-intlayer-lingui) (одна серия адаптеров)
-- [vue-i18n vs @intlayer/vue-i18n](https://intlayer.org/blog/vue-i18n-vs-intlayer-vue-i18n) (одна серия адаптеров)
-- [Руководство по миграции: next-intl на Intlayer](https://intlayer.org/doc/migration/next-intl)
-- [Справочник адаптера совместимости: next-intl](https://intlayer.org/doc/compatibility/next-intl)
+Та же серия адаптеров:
+
+- [i18next vs @intlayer/i18next](https://intlayer.org/ru/blog/i18next-vs-intlayer-i18next)
+- [Lingui vs @intlayer/lingui](https://intlayer.org/ru/blog/lingui-vs-intlayer-lingui)
+- [vue-i18n vs @intlayer/vue-i18n](https://intlayer.org/ru/blog/vue-i18n-vs-intlayer-vue-i18n)
+
+Прямое сравнение библиотек:
+
+- [next-intl vs Intlayer](https://intlayer.org/ru/blog/next-intl-vs-intlayer), тот же бенчмарк
+- [next-i18next vs next-intl vs Intlayer](https://intlayer.org/ru/blog/next-i18next-vs-next-intl-vs-intlayer)
+- [Is next-intl outdated?](https://intlayer.org/ru/blog/is-next-intl-outdated)
+
+Справочная документация:
+
+- [Compat adapter: next-intl](https://intlayer.org/ru/doc/compatibility/next-intl)
+- [Руководство по миграции: с next-intl на Intlayer](https://intlayer.org/ru/doc/migration/next-intl)
+- [Отчет о бенчмарке Next.js](https://intlayer.org/ru/doc/benchmark/nextjs) и [отчет о бенчмарке TanStack Start](https://intlayer.org/ru/doc/benchmark/tanstack)
+- [Оптимизация бандла](https://intlayer.org/ru/doc/concept/bundle-optimization) и [компилятор Intlayer](https://intlayer.org/ru/doc/compiler)
+- [Визуальный редактор](https://intlayer.org/ru/doc/concept/editor), [CMS](https://intlayer.org/ru/doc/concept/cms) и [ИИ-перевод](https://intlayer.org/ru/doc/concept/auto-fill)
 
 ## Заключение