@intlayer/docs 9.5.6 → 9.5.8

package/blog/uk/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: "Дві бібліотеки i18n на основі компілятора протестовані на 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 - це дві бібліотеки в цьому бенчмарку, які покладаються на **компілятор**, а не на чистий runtime. Lingui витягує повідомлення з макросів під час збирання та компілює каталоги для кожної локалі. Intlayer компілює словники для кожного компонента та виконує tree-shaking для кожної локалі. У теорії вони мають бути близькими. Числа показують, де вони розходяться.
 
 Дані отримані з [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom), відкритого набору тестів, який створює однаковий додаток з кожною бібліотекою та фіксує, що браузер насправді завантажує та виконує.
@@ -96,6 +98,10 @@ Intlayer не має варіанта "scoped": компілятор автом
 
 ### Результати на Next.js
 
+Виберіть метрики та бібліотеки, які вас цікавлять:
+
+<I18nBenchmark framework="nextjs" vertical/>
+
 | Бібліотека          | Стратегія      | Розмір Lib (gz) | Сер. JS сторінки (gz) | Витік локалі | Витік сторінки | Сер. компонента (gz) | Реактивність E2E | Гідратація |
 | ------------------- | -------------- | --------------: | --------------------: | -----------: | -------------: | -------------------: | ---------------: | ---------: |
 | **base** (без i18n) | -              |          0.0 KB |              141.0 KB |         0.0% |           0.0% |               0.9 KB |          13.4 ms |    11.8 ms |
@@ -114,6 +120,15 @@ Intlayer не має варіанта "scoped": компілятор автом
 - **Витік резервної мови (fallback).** Навіть в оптимізованих конфігураціях **3-15% рядків `en` потрапляють на сторінки `fr`**. Макроси Lingui зберігають початкове повідомлення як fallback, через що воно потрапляє у бандл поруч із перекладом. 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/uk/doc/benchmark/nextjs).
+
 ### Результати на TanStack Start
 
 | Бібліотека                   | Стратегія      | Розмір Lib (gz) | Сер. JS сторінки (gz) | Витік локалі | Витік сторінки | Сер. компонента (gz) | Реактивність E2E | Гідратація |
@@ -135,8 +150,19 @@ Intlayer не має варіанта "scoped": компілятор автом
 - **Рядок `static` в Intlayer вже має 0% витоку сторінки**, оскільки до бандла потрапляють лише словники, імпортовані компонентами поточної сторінки. Один рядок конфігурації (`importMode: 'dynamic'`) повністю прибирає і витік локалі.
 - **`@intlayer/lingui`** зберігає синтаксис макросів Lingui та обслуговує їх зі словників Intlayer. Це дещо збільшує розмір сторінки (137 КБ через наявність runtime макросів) заради зменшення розміру компонентів (12.8 КБ) та швидшої гідратації, ніж у нативному Lingui. Це чудовий крок для поступової міграції.
 
+<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/uk/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 @@ Intlayer не має варіанта "scoped": компілятор автом
             └── 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/uk/doc/concept/bundle-optimization).
 
@@ -184,7 +212,8 @@ Intlayer не має варіанта "scoped": компілятор автом
 
 ### Налаштування
 
-**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>`. Жодних кроків extract чи compile: словники створюються автоматично під час роботи бандлера.
 
+</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`. Якщо забути виконати цю команду або `compile`, застосунок непомітно повернеться до англійського тексту.
 
-**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>
 ### За межами компонентів
 
 Метадані, завантажувачі (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, а ваша команда звикла керувати процесом вилучення, компіляції та розділення каталогів. Розмір JS на сторінку дуже конкурентний після налаштування лінивого завантаження.
-- **Обирайте 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/uk/doc/concept/editor), [CMS](https://intlayer.org/uk/doc/concept/cms), [переклад через ШІ](https://intlayer.org/uk/doc/concept/auto-fill), [сервер MCP](https://intlayer.org/uk/doc/mcp-server)). Особливо актуально для великих модульних кодових баз і дизайн-систем.
+
+</Accordion>
+<Accordion header="Обрати @intlayer/lingui">
+
+Ви вже використовуєте Lingui і хочете поступово перейти на словники Intlayer, не змінюючи макроси. Ваші каталоги `.po` залишаються джерелом правди завдяки [плагіну синхронізації PO](https://intlayer.org/uk/doc/compatibility/lingui). Виміряно поруч у [Lingui vs @intlayer/lingui](https://intlayer.org/uk/blog/lingui-vs-intlayer-lingui).
+
+</Accordion>
+</AccordionGroup>
+
+## FAQ
+
+<FAQ>
+
+<Question title="Lingui також компілює. Чому результат настільки відрізняється?">
+
+Тому що одиниця компіляції відрізняється. Lingui компілює **один каталог на мову**: все інше (каталоги на маршрут, lazy loading, виключення резервного варіанту з бандла) вимагає налаштування. Intlayer компілює **один словник на компонент**, тому ізоляція за маршрутами виникає автоматично під час збирання. Ось чому окремо скомпільований компонент Lingui важить 58-153 KB проти 6-8 KB в Intlayer.
+
+</Question>
+
+<Question title="Чому витік локалей ніколи не досягає 0% з Lingui?">
+
+Макроси зберігають вихідне повідомлення доступним у рантаймі як резервний варіант (fallback), тому англійський рядок відправляється поруч із перекладом. Бенчмарк фіксує **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/uk/doc/compatibility/lingui).
+
+</Question>
+
+<Question title="Що щодо кроків вилучення та компіляції?">
+
+Вони залишаються для макросів і зникають для власного контенту Intlayer. Словники `.content.ts` створюються під час роботи бандлера без окремого виклику CLI, а [`intlayer test`](https://intlayer.org/uk/doc/concept/cli) зупиняє CI у разі відсутності ключа замість непомітного відкату до вихідного рядка.
+
+</Question>
+
+</FAQ>
 
 ## Схожі порівняння
 
-- [next-intl проти Intlayer](https://intlayer.org/uk/blog/next-intl-vs-intlayer) (той самий бенчмарк)
-- [i18next проти Intlayer](https://intlayer.org/uk/blog/i18next-vs-intlayer) (той самий бенчмарк)
-- [Бенчмарк vue-i18n проти Intlayer](https://intlayer.org/uk/blog/vue-i18n-vs-intlayer-benchmark) (той самий бенчмарк)
-- [Компілятор проти декларативного i18n](https://intlayer.org/uk/blog/compiler-vs-declarative-i18n)
+Той самий бенчмарк, інші бібліотеки:
+
+- [next-intl vs Intlayer](https://intlayer.org/uk/blog/next-intl-vs-intlayer)
+- [i18next vs Intlayer](https://intlayer.org/uk/blog/i18next-vs-intlayer)
+- [vue-i18n vs Intlayer benchmark](https://intlayer.org/uk/blog/vue-i18n-vs-intlayer-benchmark)
+- [next-i18next vs next-intl vs Intlayer](https://intlayer.org/uk/blog/next-i18next-vs-next-intl-vs-intlayer)
+- [react-i18next vs react-intl vs Intlayer](https://intlayer.org/uk/blog/react-i18next-vs-react-intl-vs-intlayer)
+
+Докладніше:
+
+- [Lingui vs @intlayer/lingui](https://intlayer.org/uk/blog/lingui-vs-intlayer-lingui), адаптер виміряно на тому ж застосунку
+- [Compiler-driven vs declarative i18n](https://intlayer.org/uk/blog/compiler-vs-declarative-i18n)
+- [Per-component vs centralized i18n](https://intlayer.org/uk/blog/per-component-vs-centralized-i18n)
+- [ICU message format explained](https://intlayer.org/uk/blog/icu-message-format)
+
+Довідкова документація:
+
+- [Звіт про бенчмарк Next.js](https://intlayer.org/uk/doc/benchmark/nextjs) та [звіт про бенчмарк TanStack Start](https://intlayer.org/uk/doc/benchmark/tanstack)
+- [Compat adapter: Lingui](https://intlayer.org/uk/doc/compatibility/lingui)
+- [Оптимізація бандла](https://intlayer.org/uk/doc/concept/bundle-optimization) та [компілятор Intlayer](https://intlayer.org/uk/doc/compiler)
 
 ## Зірки GitHub
 

package/blog/uk/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/uk/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 vs 14.7 мс): немає об'єкта повідомлень для десеріалізації з RSC payload перед тим, як React може гідрувати.
 - **Адаптер - це не native runtime.** `next-intlayer` займає **141.3 KB**, +0.3 KB понад базову програму, з 5.5 KB runtime. Адаптер несе поверхню 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/uk/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 мс** для оновлення `html[lang]`; адаптер потребує **4-9 мс**. Менше компонентів перерендерюється, і ніщо не переважається із дерева повідомлень.
 - **`static` зберігає кожну локаль.** Рядок адаптера `static` показує витік локалі 49.7%, той же, що й у нативному Intlayer у режимі `static`: усі локалі bundled, але лише словники сторінки. Один рядок конфігурації (`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/uk/doc/benchmark/tanstack).
+
 ## Чому змінюються цифри
 
+![The Intlayer compiler extracts content from components](https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.webp?raw=true)
+
 Ніщо в компоненті не змінилось, тому виграш повністю походить від того, до чого привʹязаний `useTranslations`.
 
-**З `next-intl`**, binding це провайдер. `NextIntlClientProvider` отримує весь об'єкт `messages` для локалі; кожен `useTranslations("about")` читає з нього. Bundler бачить один компонент, що імпортує один hook, який читає один контекст, і не може знати, що використовується тільки гілка `about`. Маршрути нижче всі ділять один і той же об'єкт messages, тому колонка page-leak читає ~90%, доки ви самі не розділите файл.
+**З `next-intl`**, binding це провайдер. `NextIntlClientProvider` отримує весь об'єкт `messages` для локалі; кожен `useTranslations("about")` читає з нього. Bundler бачить один компонент, що імпортує один hook, який читає один контекст, і не може знати, що використовується тільки гілка `about`. Маршрути нижче всі ділять один і той же об'єкт messages, тому колонка page-leak читає ~90%, доки ви самі не розділите файл, і зайве навантаження зростає за двома осями одночасно, сторінками та мовами:
+
+![Theoretical content leakage by architecture](https://github.com/aymericzip/intlayer/blob/main/docs/assets/theorical_content_leakage.webp?raw=true)
 
 ```bash
 .
@@ -280,25 +308,106 @@ export default withIntlayer(nextConfig);
 
 ## Обмеження, які варто знати перед початком
 
-- **Routing config переміщується до `intlayer.config.ts`.** `createNavigation(routing)` та `createMiddleware(routing)` зберігають свою сигнатуру, але ігнорують аргумент: locales, default locale та стратегія префіксу беруться з Intlayer's `routing` config. Якщо ви використовуєте `next-intl`'s локалізовані `pathnames` (`/about` → `/a-propos`), адаптер їх не інтерполює; Intlayer's `routing.rewrite` охоплює цей випадок, але це окрема зміна.
-- **`useTranslations()` без namespace не прив'язаний.** Optimize pass потребує static namespace, щоб знати який dictionary імпортувати. Bare call все ще працює через runtime registry, який посилається на кожен dictionary, що є точно витоком, який ви намагалися видалити. Передавайте namespace.
-- **Адаптер не безкоштовний.** 8.0 КБ runtime проти 5.5 КБ для `next-intlayer`, та +6-7 КБ на сторінку над нативною збіркою. Це плата за `next-intl` API surface. Якщо ви дійшли до точки, де кожний компонент був перенесений на `useIntlayer`, відмовтеся від адаптера.
-- **`messages`, `timeZone`, `now` на провайдері ігноруються.** Форматери підтримуються нативним `Intl` і лише locale впливає на їх вихід; якщо ви покладаєтеся на примусову часову зону або фіксований `now` для hydration-стійких дат, обробіть це на місці виклику.
+<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 все одно працює через реєстр рантайму, що посилається на кожен словник, що є саме тим витоком, який ви намагалися усунути. Передавайте простір імен.
+
+</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/uk/blog/date-time-number-formatting-locales).
+
+</Accordion>
+</AccordionGroup>
 
 ## Коли використовувати що?
 
-- **Залишайтеся на `next-intl`** якщо ваш додаток малий, ваш bundle не є проблемою, і ваша команда комфортно володіє namespaces та `pick()` на сторінку.
-- **Використовуйте `@intlayer/next-intl`**, якщо ви вже використовуєте `next-intl` і хочете отримати переваги у bundle, витоки та hydration, типізовані ключі та інструменти CLI / CMS без переписування. Це рекомендована точка входу для будь-якої існуючої codebase `next-intl`.
-- **Перейдіть на native (`next-intlayer`)** для нових проектів або після того, як адаптер виконав свою роботу. Це найлегший із трьох (5.5 KB, +0.3 KB на сторінку) і розблоковує синхронні server components, файли `.content.ts` за компонентом та повний набір функцій.
+<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/uk/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/uk/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) (бібліотеки, той же бенчмарк)
-- [i18next vs @intlayer/i18next](https://intlayer.org/blog/i18next-vs-intlayer-i18next) (та ж серія адаптерів)
-- [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/uk/blog/i18next-vs-intlayer-i18next)
+- [Lingui vs @intlayer/lingui](https://intlayer.org/uk/blog/lingui-vs-intlayer-lingui)
+- [vue-i18n vs @intlayer/vue-i18n](https://intlayer.org/uk/blog/vue-i18n-vs-intlayer-vue-i18n)
+
+Пряме порівняння бібліотек:
+
+- [next-intl vs Intlayer](https://intlayer.org/uk/blog/next-intl-vs-intlayer), той самий бенчмарк
+- [next-i18next vs next-intl vs Intlayer](https://intlayer.org/uk/blog/next-i18next-vs-next-intl-vs-intlayer)
+- [Is next-intl outdated?](https://intlayer.org/uk/blog/is-next-intl-outdated)
+
+Довідкова документація:
+
+- [Compat adapter: next-intl](https://intlayer.org/uk/doc/compatibility/next-intl)
+- [Посібник із міграції: з next-intl на Intlayer](https://intlayer.org/uk/doc/migration/next-intl)
+- [Звіт про бенчмарк Next.js](https://intlayer.org/uk/doc/benchmark/nextjs) та [звіт про бенчмарк TanStack Start](https://intlayer.org/uk/doc/benchmark/tanstack)
+- [Оптимізація бандла](https://intlayer.org/uk/doc/concept/bundle-optimization) та [компілятор Intlayer](https://intlayer.org/uk/doc/compiler)
+- [Візуальний редактор](https://intlayer.org/uk/doc/concept/editor), [CMS](https://intlayer.org/uk/doc/concept/cms) та [переклад за допомогою ШІ](https://intlayer.org/uk/doc/concept/auto-fill)
 
 ## Висновок