@intlayer/docs 8.12.5-canary.0 → 9.0.0-canary.11

package/docs/uk/cli/scan.md

@@ -18,7 +18,7 @@ slugs:
   - cli
   - scan
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-11
     changes: "Додано вміст команди scan"
 author: aymericzip

package/docs/uk/compat/i18n-js.md

@@ -0,0 +1,44 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Міграція з i18n-js на Intlayer"
+description: "Дізнайтеся, як перенести вашу програму з i18n-js на Intlayer за допомогою адаптера сумісності."
+keywords:
+  - i18n-js
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - i18n-js
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Міграція з i18n-js на Intlayer
+
+Перехід з бібліотеки `i18n-js` на Intlayer — це високооптимізована міграція, розроблена для переведення великих конфігурацій перекладів у структуровану систему розділення файлів Intlayer.
+
+## Що робити
+
+Виконайте наступну команду налаштування у вашому репозиторії:
+
+```bash
+npx intlayer init
+```
+
+З підготовленим `intlayer.config.ts`, ви можете додати alias Intlayer до конфігурації вашого bundler, щоб будь-які імпорти `i18n-js` спрямовувалися на пакет сумісності `@intlayer/i18n-js`.
+
+## Що він робить під капотом
+
+`i18n-js` accesses namespaces through expressions like `i18n.t('scope.key', {name})` along with locale fallbacks and specific plural mappings.
+
+Under the hood:
+
+- **Interpolation:** The compat adapter easily parses `%{name}` mappings into your targeted runtime dictionary value.
+- **Pluralization:** Replaces `one/other` subkeys and maps them against Intlayer's powerful underlying plural mechanisms (`Intl.PluralRules`), abstracting away manual mappings.
+- **Locales:** Instead of loading monolithic language payloads at bootstrap, dictionaries are served up optimally based on the current context setup via the native Intlayer configuration.

package/docs/uk/compat/i18next.md

@@ -0,0 +1,59 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Перейти з i18next на Intlayer"
+description: "Дізнайтеся, як перенести вашу програму Vanilla JS/TS з i18next на Intlayer, використовуючи адаптер сумісності."
+keywords:
+  - i18next
+  - vanilla
+  - javascript
+  - typescript
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - i18next
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Міграція з i18next на Intlayer
+
+Для детального покрокового посібника дивіться наш повний [Посібник з міграції з i18next](../migration_from_i18next_to_intlayer.md).
+
+Intlayer ідеально повторює основні характеристики виконання `i18next`. Використовуючи пакет compat, ваші Vanilla-додатки або внутрішні модулі можуть продовжувати використовувати звичний синтаксис.
+
+## Що робити
+
+Щоб розпочати, ініціалізуйте Intlayer у своєму проекті:
+
+```bash
+npx intlayer init
+```
+
+Якщо ви використовуєте Vite, включіть плагін Intlayer для маршрутизації імпортів до `@intlayer/i18next`:
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { i18nextVitePlugin } from "@intlayer/i18next/plugin";
+
+export default defineConfig({
+  plugins: [i18nextVitePlugin()],
+});
+```
+
+## Як це працює під капотом
+
+`i18nextVitePlugin` переспрямовує імпорти `i18next` на `@intlayer/i18next`, уникаючи збільшення розміру bundle через включення JSON файлів.
+
+Під капотом:
+
+- **Конфігурація екземпляра:** `createInstance` правильно парсить та застосовує fallbacks простору імен, одночасно використовуючи конвеєр компіляції Intlayer для отримання словників.
+- **Інтерполяція:** Нативна підтримка замін `{{name}}` та вкладеного `$t(key)` рекурсивно.
+- **Контекст і плюралізація:** Визначає та розв'язує формати суфіксів на кшталт `key_male` та `key_one`/`key_other`, оцінюючи їх за стандартом `Intl.PluralRules`.
+- **Повернення об'єктів:** Режим `returnObjects: true` безпечно витягує дерева з словників Intlayer.

package/docs/uk/compat/index.md

@@ -0,0 +1,51 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Адаптери сумісності Intlayer"
+description: "Мігруйте своє існуюче рішення i18n на Intlayer без зусиль, використовуючи адаптери сумісності."
+keywords:
+  - compat
+  - migration
+  - internationalization
+  - i18n
+  - Intlayer
+slugs:
+  - doc
+  - compatibility
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Compat адаптери Intlayer
+
+Міграція великої програми на нову бібліотеку інтернаціоналізації може бути складною. Щоб полегшити цей перехід, Intlayer надає **compat адаптери** для найпопулярніших i18n бібліотек в екосистемі.
+
+Ці пакети адаптерів надають **точно такий самий публічний API**, як ваші існуючі i18n бібліотеки, але делегують усю роботу перекладу в Intlayer під час виконання.
+
+## Як це працює
+
+Коли ви використовуєте compat adapter, вам не потрібно переписувати імпорти вашої програми або змінювати те, як ви користуєтеся translation hooks та компонентами. Замість цього, плагіни bundler Intlayer автоматично створюють alias ваших існуючих імпортів на Intlayer compat пакети.
+
+Наприклад, розробник замінює `import { useTranslation } from 'react-i18next'` на `import { useTranslation } from '@intlayer/react-i18next'` (робиться автоматично через плагін bundler), і програма продовжує працювати з перекладами, які тепер надаються з Intlayer словників. Ключі також типізовані щодо ваших Intlayer словників!
+
+## Доступні адаптери сумісності
+
+Виберіть вашу існуючу бібліотеку нижче, щоб дізнатися, як легко перейти:
+
+- [Vue I18n](./vue-i18n.md)
+- [Transloco](./transloco.md)
+- [React Intl](./react-intl.md)
+- [Svelte I18n](./svelte-i18n.md)
+- [React i18next](./react-i18next.md)
+- [Polyglot.js](./polyglot.md)
+- [NuxtJS I18n](./nuxtjs-i18n.md)
+- [NGX Translate](./ngx-translate.md)
+- [Next Translate](./next-translate.md)
+- [Next Intl](./next-intl.md)
+- [Next i18next](./next-i18next.md)
+- [i18next](./i18next.md)
+- [Lingui](./lingui.md)
+- [I18n-js](./i18n-js.md)

package/docs/uk/compat/lingui.md

@@ -0,0 +1,44 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Міграція з Lingui на Intlayer"
+description: "Дізнайтеся, як мігрувати вашу програму з Lingui на Intlayer, використовуючи адаптер сумісності."
+keywords:
+  - lingui
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - lingui
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Міграція з Lingui на Intlayer
+
+Якщо ваш проект наразі використовує компіляцію на основі макросів Lingui, перехід на Intlayer дозволяє вам зберегти потужні робочі процеси макросів, одночасно підтримуючи їх нативно за допомогою стратегії JSON-компіляції Intlayer.
+
+## Що робити
+
+Для початку ініціалізуйте Intlayer у своєму проекті:
+
+```bash
+npx intlayer init
+```
+
+Це створює ваш `intlayer.config.ts`. Переконайтеся, що ви зберегли `@lingui/babel-plugin-lingui-macro` / `@lingui/swc-plugin` у вашому кроці збірки для запуску _перед_ компілятором Intlayer. Потім використовуйте alias плагіна bundler для маршрутизації `@lingui/core` та `@lingui/react` до `@intlayer/lingui`.
+
+## Як це працює під капотом
+
+Lingui використовує макроси (такі як `` t`Hello ${name}` `` та `<Trans>`), які компілюються в runtime-виклики типу `i18n._(id, values)`.
+
+Під капотом:
+
+- **Макроси:** Вони компілюються точно так же, як раніше, забезпечуючи відсутність порушень у вашому синтаксисі вихідного коду.
+- **Runtime-переклад:** Псевдонім `i18n._()` використовує словники Intlayer. Як явно названі ID, так і захешовані ID повністю відображаються за допомогою плагінів синхронізації `.po` Intlayer для безпечної агрегації та видалення ключів.
+- **Можливості ICU:** Підтримка плюралізації, вибору та варіантів ICU залишається стійкою завдяки уніфікованому ICU-парсеру Intlayer, забезпечуючи однакові результати рендерингу.

package/docs/uk/compat/next-i18next.md

@@ -0,0 +1,57 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Міграція з next-i18next на Intlayer"
+description: "Дізнайтеся, як перенести своє Next.js додаток з next-i18next на Intlayer за допомогою адаптера сумісності."
+keywords:
+  - next-i18next
+  - nextjs
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - next-i18next
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Міграція з next-i18next на Intlayer
+
+Для повного та детального покрокового посібника, будь ласка, див. наш [Посібник з міграції next-i18next](../migration_from_next-i18next_to_intlayer.md).
+
+Intlayer прозоро обробляє всі реалізації Next.js Pages Router та App Router. Використання адаптера дозволяє вам перенести вашу реалізацію `next-i18next` без переписування коду.
+
+## Що робити
+
+Для початку виконайте:
+
+```bash
+npx intlayer init
+```
+
+Це створює необхідний файл конфігурації Intlayer. Щоб інтегрувати Intlayer в фоновому режимі, оновіть ваш `next.config.ts`:
+
+```typescript fileName="next.config.ts"
+import type { NextConfig } from "next";
+import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
+
+const withIntlayer = createNextI18nPlugin();
+
+const nextConfig: NextConfig = {};
+
+export default withIntlayer(nextConfig);
+```
+
+## Що він робить під капотом
+
+`createNextI18nPlugin` поєднує нативну поведінку Next.js разом з основним плагіном `next-intlayer`, інжектуючи всі необхідні псевдоніми Webpack/Turbopack для `next-i18next`, `react-i18next` та `i18next`.
+
+Під капотом:
+
+- **`serverSideTranslations` & `appWithTranslation`:** Тепер вони функціонують як обгортки для внутрішніх завантажувачів Intlayer, обходячи велику статичну ін'єкцію JSON.
+- **Client hooks:** Негайно делегує до `@intlayer/react-i18next`, збереження всі функції форматування, множин та вкладених просторів імен.

package/docs/uk/compat/next-intl.md

@@ -0,0 +1,59 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Міграція з next-intl на Intlayer"
+description: "Дізнайтеся, як мігрувати вашу Next.js програму з next-intl на Intlayer за допомогою адаптера сумісності."
+keywords:
+  - next-intl
+  - nextjs
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - next-intl
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Переміщення з next-intl на Intlayer
+
+Для повного та детального покрокового посібника, будь ласка, см. наш повний [посібник з міграції next-intl](../migration_from_next-intl_to_intlayer.md).
+
+Переміщення з `next-intl` на Intlayer дозволяє вам повністю зберегти маршрутизацію та синтаксис вашої програми без змін.
+
+## Що робити
+
+Виконайте наступну команду у вашому репозиторії:
+
+```bash
+npx intlayer init
+```
+
+Це створить файл `intlayer.config.ts`. У вашому `next.config.ts` використовуйте обгортку плагіна, щоб безперешкодно вприскити `next-intl` aliases до `@intlayer/next-intl`.
+
+```typescript fileName="next.config.ts"
+import type { NextConfig } from "next";
+import { createNextIntlPlugin } from "@intlayer/next-intl/plugin";
+
+const withIntlayer = createNextIntlPlugin();
+
+const nextConfig: NextConfig = {};
+
+export default withIntlayer(nextConfig);
+```
+
+## Що це робить під капотом
+
+The bundler wrapper замінює переклади, але **залишає функції `next-intl/navigation` без змін** (наприклад, `Link`, `redirect`, `usePathname`).
+
+Під капотом:
+
+- **ICU runtime:** Множини (`=0`, `one`, `other`), select/selectordinal, аргументи `#` та форматовані аргументи (`{ts, date, long}`) працюють правильно за допомогою спільного резолвера `resolveMessage(..., 'icu')`.
+- **`useTranslations()` & `getTranslations()`:** Виклики без області видимості витягують перший сегмент ключа як правильний ідентифікатор словника. Вкладені простори імен грацильно розділяються на шляхи словника та префікси.
+- **Rich formatting:** Обидва `t.rich()` і `t.markup()` повністю рідко реалізовані, перетворюючи HTML-подібні вузли на відтворені React-куски.
+- **`useFormatter`:** `relativeTime`, `list`, `dateTimeRange` та названі формати з конфігурації переходять до основних нативних форматерів `Intl`.

package/docs/uk/compat/next-translate.md

@@ -0,0 +1,45 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Міграція з Next Translate на Intlayer"
+description: "Дізнайтеся, як перенести вашу програму Next.js з next-translate на Intlayer, використовуючи адаптер сумісності."
+keywords:
+  - next-translate
+  - nextjs
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - next-translate
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Міграція з Next Translate на Intlayer
+
+Міграція з `next-translate` на Intlayer є практично прямою заміною, яка зберігає вашу існуючу синтаксис та теги.
+
+## Що робити
+
+Initialize Intlayer у вашому проекті:
+
+```bash
+npx intlayer init
+```
+
+CLI створить вашу конфігурацію. Потім ви можете застосувати плагін Intlayer у вашому `next.config.ts`, який injects build-time subpath aliases mapping `next-translate/useTranslation` to `@intlayer/next-translate`.
+
+## Як це працює під капотом
+
+`next-translate` надає хуки як `useTranslation('ns')`, `t('ns:key.path')` та компонент `<Trans>`.
+
+Під капотом:
+
+- **Інтерполяція та множини:** Він тісно покладається на поведінку адаптера `react-i18next`. Динамічно обробляються заповнювачі `{{var}}` та плюралізація, відображена з суфіксів як `key_0`, `key_one` та `key_other`.
+- **Компонент `<Trans>`:** Безпосередньо підтримується для аналізу HTML-подібних тегів разом із реквізитом `components` на основі масиву.
+- **Простори імен:** Aliasing підпутей забезпечує, що ваш `useTranslation` посилається на правильні внутрішні простори імен словника без ручного змінення.

package/docs/uk/compat/ngx-translate.md

@@ -0,0 +1,45 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Міграція з NGX-Translate на Intlayer"
+description: "Дізнайтеся, як перенести вашу Angular-застосунок з ngx-translate на Intlayer за допомогою адаптера сумісності."
+keywords:
+  - ngx-translate
+  - angular
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - ngx-translate
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Ініціалізація історії"
+author: aymericzip
+---
+
+# Міграція з NGX-Translate на Intlayer
+
+Міграція вашої Angular-програми з `ngx-translate` на Intlayer легка за допомогою адаптера сумісності, що дозволяє вам уникнути необхідності переписувати всі ваші шаблони.
+
+## Що робити
+
+Почніть з виконання:
+
+```bash
+npx intlayer init
+```
+
+Це налаштовує `intlayer.config.ts`. Замініть ваші налаштування `TranslateModule.forRoot()` та імпорт альіасів відповідно, щоб вони вказували на `@intlayer/ngx-translate`.
+
+## Що це робить під капотом
+
+`ngx-translate` використовує `TranslateService` (`instant`, `get`, `stream`) разом з pipe `{{ 'KEY' | translate:params }}` та директивою `[translate]`.
+
+Під капотом:
+
+- **Services:** `TranslateService` обгортає `getIntlayer` та locale observable, забезпечуючи точно такі ж методи.
+- **Pipes & Directives:** Переімплементовані для прямого розв'язання проти словників Intlayer.
+- **Loaders:** Конфігурації `TranslateHttpLoader` перетворюються на заглушки попередження, тому що Intlayer за своєю суттю розв'язує та пакує ваші словники під час збірки (або через стандартні динамічні імпорти), повністю усуваючи необхідність у HTTP loaders.

package/docs/uk/compat/nuxtjs-i18n.md

@@ -0,0 +1,46 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Міграція з NuxtJS I18n на Intlayer"
+description: "Дізнайтеся, як перенести вашу програму Nuxt.js з @nuxtjs/i18n на Intlayer за допомогою адаптера compat."
+keywords:
+  - nuxtjs-i18n
+  - nuxt
+  - vue
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - nuxtjs-i18n
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Перехід з NuxtJS I18n на Intlayer
+
+Перехід вашої Nuxt-програми з `@nuxtjs/i18n` на Intlayer є безперебійним процесом за допомогою модуля адаптера Nuxt.
+
+## Що робити
+
+Щоб ініціалізувати проект, запустіть:
+
+```bash
+npx intlayer init
+```
+
+Це налаштує `intlayer.config.ts`. Потім додайте модуль Intlayer Nuxt (наприклад `@intlayer/nuxt-i18n`) у масив modules вашого `nuxt.config.ts`. Це автоматично застосує конфігурацію сумісності для вашої програми.
+
+## Що він робить під капотом
+
+`@nuxtjs/i18n` обгортає `vue-i18n`, надаючи Nuxt-специфічні routing composables (`useLocalePath`, `useSwitchLocalePath`, `<NuxtLinkLocale>`).
+
+Під капотом:
+
+- **Translations:** Покладається нативно на `@intlayer/vue-i18n` compat layer для всіх завдань трансляції рядків (повністю підтримуючи формати `vue-i18n`, pipe plurals та reactivity).
+- **Routing:** Відзеркалює routing composables, використовуючи Intlayer's localized URL helpers.
+- **Configuration:** Читає `availableLocales` та параметри за замовчуванням прямо з вашого `intlayer.config.ts` для автоматичної координації сторінок Nuxt.

package/docs/uk/compat/polyglot.md

@@ -0,0 +1,45 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Міграція з Polyglot.js на Intlayer"
+description: "Дізнайтеся, як перейти з Polyglot.js на Intlayer, використовуючи адаптер сумісності."
+keywords:
+  - polyglot
+  - airbnb
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - polyglot
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Міграція з Polyglot.js на Intlayer
+
+Якщо ви використовуєте Polyglot.js від Airbnb, міграція на Intlayer є надзвичайно простою за допомогою рівня сумісності.
+
+## Що робити
+
+Просто запустіть команду ініціалізації у вашому проекті:
+
+```bash
+npx intlayer init
+```
+
+Це генерує `intlayer.config.ts`. Потім ви можете використовувати alias bundler plugin для прозорого перенаправлення Polyglot imports на `@intlayer/polyglot`.
+
+## Що робиться під капотом
+
+Синтаксис Polyglot.js зазвичай спирається на `polyglot.t('key', {name})` з інтерполяціями `%{name}` та множинами `smart_count`, розділеними на `"singular |||| plural"`.
+
+Під капотом:
+
+- **Interpolation:** Рівень сумісності обробляє заповнювачі `%{var}` нативно.
+- **Plurals:** Рядок розділяється на `||||` і оцінюється проти нативного `Intl.PluralRules` відповідно до активної локалі, дзеркалюючи власний порядок buckets Polyglot за локаллю.
+- **Dictionaries:** Ви обходите потребу надавати великі конфігурації JSON до `new Polyglot()` – Intlayer обробляє словники динамічно та обрізує їх автоматично.

package/docs/uk/compat/react-i18next.md

@@ -0,0 +1,58 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Міграція з react-i18next на Intlayer"
+description: "Дізнайтесь, як мігрувати свій React додаток з react-i18next на Intlayer за допомогою адаптера сумісності."
+keywords:
+  - react-i18next
+  - i18next
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - react-i18next
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Міграція з react-i18next на Intlayer
+
+Для повного та детального покрокового посібника дивіться наш повний [Посібник міграції з react-i18next](../migration_from_react-i18next_to_intlayer.md).
+
+Використання адаптера сумісності Intlayer дозволяє вам перейти з `react-i18next` без будь-яких змін у імпортах вихідного коду.
+
+## Що робити
+
+Щоб ініціалізувати проект, виконайте:
+
+```bash
+npx intlayer init
+```
+
+Під час ініціалізації Intlayer встановить `@intlayer/react-i18next` і створить `intlayer.config.ts`. У вашому bundler (наприклад, Vite) застосуйте плагін Intlayer:
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { reactI18nextVitePlugin } from "@intlayer/react-i18next/plugin";
+
+export default defineConfig({
+  plugins: [react(), reactI18nextVitePlugin()],
+});
+```
+
+## Що воно робить під капотом
+
+`reactI18nextVitePlugin` обгортає основний плагін `vite-intlayer` і вводить alias'и розділення для `react-i18next` та `i18next`, перенаправляючи їх на `@intlayer/react-i18next` та `@intlayer/i18next`.
+
+Під капотом:
+
+- **`useTranslation` & `withTranslation`:** Переписано для використання нативних хуків Intlayer, що дає вам автоматичне завершення TypeScript для ключів вашого словника. Безпроблемно підтримує простори імен (наприклад `t('namespace:key')`).
+- **Множини & Контекст:** Обробляє pluralization на основі суфіксів в i18next (`key_one`, `key_other`) з використанням нативного `Intl.PluralRules` та суфіксів контексту (`key_male`).
+- **`<Trans>` Компонент:** Перереалізований для підтримки пропса `components`, форм об'єкта та масиву, а також нумерованих тегів `<1>...</1>` з прямим відображенням на ваші React-вузли.
+- **`i18n` екземпляр:** Розв'язує ключі безпосередньо з Intlayer без завантаження великих JSON-файлів, що призводить до значно менших розмірів bundle.

package/docs/uk/compat/react-intl.md

@@ -0,0 +1,55 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Міграція з React Intl на Intlayer"
+description: "Дізнайтеся, як перенести вашу React-додаток з react-intl на Intlayer, використовуючи адаптер сумісності."
+keywords:
+  - react-intl
+  - formatjs
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - react-intl
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Перехід від React Intl до Intlayer
+
+Якщо ваш React додаток використовує `react-intl` (FormatJS), перехід на Intlayer — це просто. Наш compat layer безпроблемно обробляє ICU MessageFormat та всі існуючі компоненти `Formatted*`.
+
+## Що робити
+
+Почніть із запуску команди ініціалізації у вашому проекті:
+
+```bash
+npx intlayer init
+```
+
+Потім налаштуйте плагін Intlayer Vite або Next.js у вашій конфігурації. Цей плагін вводить alias'и часу збірки для перенаправлення імпортів `react-intl` на `@intlayer/react-intl`.
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import reactIntlVitePlugin from "@intlayer/react-intl/plugin";
+
+export default defineConfig({
+  plugins: [react(), reactIntlVitePlugin()],
+});
+```
+
+## Що він робить під капотом
+
+Плагін bundler створює alias `react-intl` на `@intlayer/react-intl`. Замість ручного парсингу великих JSON файлів та обгортання вашого додатку в `IntlProvider`, плагін Intlayer статично витягує ключі та використовує словники Intlayer під час виконання.
+
+Під капотом:
+
+- **ICU MessageFormat:** Intlayer використовує resolver `resolveMessage(..., 'icu')` який повністю підтримує ICU множину, вибір, форматування дати/числа та теги багатого тексту нативно.
+- **Методи та JSX callers:** `intl.formatMessage({ id: 'a.b' })` та `<FormattedMessage id="a.b">` ідентифікуються плагінами компілятора Intlayer (`@intlayer/babel` / `@intlayer/swc`), конвертуючи плоскі ключі з крапками так, щоб перший сегмент коректно розв'язувався на ключ словника Intlayer.
+- **Форматери:** `<FormattedNumber>`, `<FormattedDate>` тощо мостять до нативних `core/formatters` використовуючи `Intl`.