@intlayer/docs 8.7.4 → 8.7.5

package/docs/uk/benchmark/nextjs.md

@@ -0,0 +1,227 @@
+---
+createdAt: 2026-04-20
+updatedAt: 2026-04-21
+title: Найкраще i18n рішення для Next.js у 2026 році - Звіт бенчмарку
+description: Порівняйте бібліотеки інтернаціоналізації (i18n) для Next.js, такі як next-intl, next-i18next та Intlayer. Детальний звіт про продуктивність за розміром бандла, витоком та реактивністю.
+keywords:
+  - benchmark
+  - i18n
+  - intl
+  - nextjs
+  - продуктивність
+  - intlayer
+slugs:
+  - doc
+  - benchmark
+  - nextjs
+author: Aymeric PINEAU
+applicationTemplate: https://github.com/intlayer-org/benchmark-i18n
+history:
+  - version: 8.7.5
+    date: 2026-01-06
+    changes: "Ініціалізація бенчмарку"
+---
+
+# Бібліотеки i18n для Next.js — Звіт бенчмарку 2026
+
+Ця сторінка є звітом бенчмарку i18n рішень на Next.js.
+
+## Зміст
+
+<Toc/>
+
+## Інтерактивний бенчмарк
+
+<I18nBenchmark framework="nextjs" vertical/>
+
+## Довідка за результатами:
+
+<iframe 
+  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;">
+</iframe>
+
+> https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-nextjs.md
+
+Дивіться повний репозиторій бенчмарку [тут](https://github.com/intlayer-org/benchmark-i18n).
+
+## Вступ
+
+Бібліотеки інтернаціоналізації мають великий вплив на ваш додаток. Основний ризик полягає в завантаженні контенту для кожної сторінки та кожної мови, коли користувач відвідує лише одну сторінку.
+
+У міру зростання додатку розмір бандла може збільшуватися в геометричній прогресії, що помітно погіршує продуктивність.
+
+Наприклад, у найгірших випадках інтернаціоналізована сторінка може стати майже в 4 рази важчою.
+
+Інший вплив бібліотек i18n — сповільнення розробки. Перетворення компонентів на багатомовний контент багатьма мовами займає багато часу.
+
+Оскільки це складна проблема, існує багато рішень — деякі зосереджені на DX (досвід розробника), інші на продуктивності чи масштабованості тощо.
+
+Intlayer намагається оптимізувати всі ці параметри одночасно.
+
+## Протестуйте свій додаток
+
+Щоб виявити ці проблеми, я створив безкоштовний сканер, який ви можете спробувати [тут](https://intlayer.org/i18n-seo-scanner).
+
+<iframe src="https://intlayer.org/i18n-seo-scanner" width="100%" height="600px" style="border:none;"/>
+
+## Проблема
+
+Є два основні способи обмежити вплив багатомовного додатку на ваш бандл:
+
+- Розділіть ваш JSON (або контент) на файли / змінні / простори імен (namespaces), щоб бандлер міг видалити невикористаний контент (tree-shaking) для конкретної сторінки.
+- Динамічно завантажуйте контент сторінки лише мовою користувача.
+
+Технічні обмеження цих підходів:
+
+**Динамічне завантаження**
+
+Навіть якщо ви оголошуєте роути на кшталт `[locale]/page.tsx`, використовуючи Webpack або Turbopack, і навіть якщо визначено `generateStaticParams`, бандлер не розглядає `locale` як статичну константу. Це означає, що він може додати контент для всіх мов у кожну сторінку. Основний спосіб обмежити це — завантажувати контент через динамічний імпорт (наприклад, `import('./locales/${locale}.json')`).
+
+На етапі збірки (build time) Next.js створює один JS-бандл на локаль (наприклад, `./locales_uk_12345.js`). Після того, як сайт надіслано клієнту, під час запуску сторінки браузер робить додатковий HTTP-запит для потрібного JS-файлу.
+
+> Інший спосіб вирішення цієї проблеми — використання `fetch()` для динамічного завантаження JSON. Саме так працює `Tolgee`, коли JSON знаходиться в `/public`, або `next-translate`, який використовує `getStaticProps` для завантаження контенту. Процес ідентичний: браузер робить додатковий HTTP-запит для завантаження ресурсу.
+
+**Розділення контенту (Content splitting)**
+
+Якщо ви використовуєте синтаксис на кшталт `const t = useTranslation()` + `t('my-object.my-sub-object.my-key')`, зазвичай весь JSON має бути в бандлі, щоб бібліотека могла розібрати його та знайти ключ. Велика частина цього контенту передається клієнту, навіть якщо вона не використовується на сторінці.
+
+Щоб мінімізувати це, деякі бібліотеки просять вас вказувати для кожної сторінки, які простори імен завантажувати — наприклад, `next-i18next`, `next-intl`, `lingui`, `next-translate`, `next-international`.
+
+Натомість `Paraglide` додає додатковий крок перед збіркою, щоб перетворити JSON на плоскі символи на кшталт `const en_my_var = () => 'my value'`. Теоретично це дозволяє видаляти невикористаний контент на сторінці. Як ми побачимо, цей метод все одно має свої компроміси.
+
+Нарешті, `Intlayer` застосовує оптимізацію на етапі збірки, завдяки чому `useIntlayer('my-key')` замінюється безпосередньо відповідним контентом.
+
+## Методологія
+
+Для цього бенчмарку ми порівняли наступні бібліотеки:
+
+- `Base App` (Без бібліотеки i18n)
+- `next-intlayer` (v8.7.5)
+- `next-i18next` (v16.0.5)
+- `next-intl` (v4.9.1)
+- `@lingui/core` (v5.3.0)
+- `next-translate` (v3.1.2)
+- `next-international` (v1.3.1)
+- `@inlang/paraglide-js` (v2.15.1)
+- `tolgee` (v7.0.0)
+- `@lingo.dev/compiler` (v0.4.0)
+- `wuchale` (v0.22.11)
+- `gt-next` (v6.16.5)
+
+Я використовував `Next.js` версії `16.2.4` з App Router.
+
+Я побудував багатомовний додаток з **10 сторінками** та **10 мовами**.
+
+Я порівняв **чотири стратегії завантаження**:
+
+| Стратегія                  | Без просторів імен (global)                             | З просторами імен (scoped)                                                |
+| :------------------------- | :------------------------------------------------------ | :------------------------------------------------------------------------ |
+| **Статичне завантаження**  | **Static**: Все в пам'яті при запуску.                  | **Scoped static**: Розділено за простором імен; завантаження при запуску. |
+| **Динамічне завантаження** | **Dynamic**: Завантаження за запитом для кожної локалі. | **Scoped dynamic**: Гранулярне завантаження за простором імен та локаллю. |
+
+## Резюме стратегій
+
+- **Static**: Просто; відсутня мережева затримка після початкового завантаження. Мінус: великий розмір бандла.
+- **Dynamic**: Зменшує початкову вагу (lazy-loading). Ідеально, якщо у вас багато локалей.
+- **Scoped static**: Зберігає код структурованим (логічний поділ) без складних мережевих запитів.
+- **Scoped dynamic**: Найкращий підхід для _розділення коду_ (code splitting) та продуктивності. Мінімізує обсяг пам'яті, завантажуючи лише те, що потрібно поточному перегляду та активній локалі.
+
+### Що я вимірював:
+
+Я запускав один і той самий багатомовний додаток у реальному браузері для кожного стеку, а потім фіксував, що насправді передавалося через мережу і скільки часу це займало. Розміри вказані **після звичайного веб-стиснення**, оскільки це ближче до того, що люди реально завантажують.
+
+- **Розмір бібліотеки інтернаціоналізації**: Після складання, видалення невикористаного коду та мінімізації, розмір бібліотеки i18n — це розмір коду провайдерів (наприклад, `NextIntlClientProvider`) + хуків (наприклад, `useTranslations`) у порожньому компоненті. Це не включає завантаження файлів перекладу. Це показує, наскільки "важкою" є бібліотека ще до появи вашого контенту.
+
+- **JavaScript на сторінку**: Для кожного тестового маршруту — скільки скриптів завантажує браузер під час візиту, усереднено за сторінками тесту (і за локалями). Важкі сторінки — це повільні сторінки.
+
+- **Витік з інших локалей (Leakage)**: Це контент тієї ж сторінки, але іншою мовою, який помилково завантажується на сторінку, що перевіряється. Цей контент є зайвим і його слід уникати (наприклад, контент сторінки `/fr/about` у бандлі сторінки `/en/about`).
+
+- **Витік з інших маршрутів**: Та ж ідея для **інших екранів** у додатку: чи передаються їхні тексти, коли ви відкрили лише одну сторінку (наприклад, контент сторінки `/en/about` у бандлі сторінки `/en/contact`). Високий показник свідчить про слабке розділення або занадто широкі бандли.
+
+- **Середній розмір бандла компонента**: Окремі UI-елементи вимірюються **по одному**, а не ховаються всередині одного гігантського загального показника додатку. Це показує, чи інтернаціоналізація "роздуває" звичайні компоненти. Наприклад, якщо ваш компонент перерендериться, він завантажуватиме всі ці дані з пам'яті. Прив'язка гігантського JSON до будь-якого компонента схожа на підключення великого сховища невикористаних даних, що сповільнює продуктивність ваших компонентів.
+
+- **Швидкість реакції на перемикання мови**: Я перемикаю мову через власний інтерфейс додатку і заміряю час до моменту, коли сторінка явно оновилася — те, що помітить відвідувач.
+
+- **Робота рендерингу після зміни мови**: Вужчий показник: скільки зусиль витратив інтерфейс на перемальовування для нової мови після початку перемикання. Корисно, коли "відчутний" час і вартість роботи фреймворку відрізняються.
+
+- **Час початкового завантаження сторінки**: Від навігації до моменту, коли браузер вважає сторінку повністю завантаженою для тестованих сценаріїв. Корисно для порівняння "холодних стартів".
+
+- **Час гідратації (Hydration)**: Час, який клієнт витрачає на перетворення HTML від сервера на інтерактивний інтерфейс. Прочерк у таблицях означає, що дана реалізація не надала надійних даних про гідратацію в цьому тесті.
+
+## Детальні результати
+
+### 1 — Рішення, яких слід уникати
+
+Деяких рішень, таких як `gt-next` або `lingo.dev`, явно варто уникати. Вони поєднують прив'язку до вендора (vendor lock-in) із засміченням кодової бази. Попри багато годин спроб їх впровадження, я так і не зміг забезпечити їх стабільну роботу — ні на TanStack Start, ні на Next.js.
+
+Виявлені проблеми:
+
+**(General Translation)** (`gt-next@6.16.5`):
+
+- Для додатку розміром 110 КБ `gt-react` додає понад 440 КБ зайвих даних.
+- `Quota Exceeded, please upgrade your plan` вже під час першої збірки.
+- Переклади не рендериться; отримую помилку `Error: <T> used on the client-side outside of <GTProvider>`, що схоже на баг бібліотеки.
+- При впровадженні **gt-tanstack-start-react** я також стикнувся з [проблемою](https://github.com/generaltranslation/gt/issues/1210#event-24510646961) бібліотеки: помилка `does not provide an export named 'printAST' - @formatjs/icu-messageformat-parser`, через яку додаток падав. Після звіту про помилку розробник виправив її протягом 24 годин.
+- Бібліотека блокує статичний рендеринг сторінок Next.js.
+
+**(Lingo.dev)** (`@lingo.dev/compiler@0.4.0`):
+
+- Перевищено квоту AI, що повністю блокує збірку — ви не можете випустити продукт у продакшн без оплати.
+- Компілятор пропустив майже 40% перекладеного контенту. Мені довелося переписувати всі `.map` у плоскі блоки компонентів, щоб це запрацювало.
+- Їхній CLI працює нестабільно і часто без причини скидає конфігураційний файл.
+- Під час збірки він повністю стирав згенеровані JSON-файли при додаванні нового контенту. У результаті кілька ключів могли знищити понад 300 наявних.
+
+### 2 — Експериментальні рішення
+
+**(Wuchale)** (`wuchale@0.22.11`):
+
+Ідея `Wuchale` цікава, але поки не життєздатна. Я зіткнувся з проблемами реактивності та був змушений примусово перерендерити провайдер, щоб додаток запрацював. Документація також досить нечітка, що ускладнює освоєння.
+
+**(Paraglide)** (`@inlang/paraglide-js@2.15.1`):
+
+`Paraglide` пропонує інноваційний, добре продуманий підхід. Проте в цьому тесті рекламований tree-shaking не спрацював для моїх налаштувань Next.js або TanStack Start. Робочий процес і DX складніші за інші варіанти.
+Особисто мені не подобається необхідність регенерувати JS-файли перед кожним пушем, що створює постійний ризик конфліктів під час злиття через PR. Інструмент також здається більш орієнтованим на Vite, ніж на Next.js.
+Нарешті, порівняно з іншими рішеннями, Paraglide не використовує стор (наприклад, React context) для отримання поточної локалі для рендерингу. Для кожного обробленого вузла він запитує локаль з localStorage / cookie тощо. Це призводить до виконання непотрібної логіки, що впливає на реактивність компонентів.
+
+### 3 — Прийнятні рішення
+
+**(Tolgee)** (`tolgee@7.0.0`):
+
+`Tolgee` вирішує багато зі згаданих проблем. Проте його впровадження здалося мені складнішим, ніж у подібних інструментів. Він не забезпечує типізацію (type safety), що ускладнює виявлення відсутніх ключів під час компіляції. Мені довелося обертати функції Tolgee своїми, щоб додати перевірку відсутніх ключів.
+
+**(Next Intl)** (`next-intl@4.9.1`):
+
+`next-intl` — це зараз найбільш трендовий варіант, який ШІ-агенти просувають найбільше, але на мій погляд, помилково. Почати роботу легко. На практиці ж оптимізація для обмеження витоків є складною. Поєднання динамічного завантаження + просторів імен + типів TypeScript сильно сповільнює розробку. Пакет також досить важкий (~13 КБ для `NextIntlClientProvider` + `useTranslations`, що майже вдвічі більше за `next-intlayer`). **next-intl** раніше блокував статичний рендеринг сторінок Next.js. Він надає хелпер `setRequestLocale()`. Здається, це частково вирішено для централізованих файлів на кшталт `en.json` / `fr.json`, але статичний рендеринг все одно ламається, коли контент розділений на простори імен, як-от `en/shared.json` / `fr/shared.json` / `es/shared.json`.
+
+**(Next I18next)** (`next-i18next@16.0.5`):
+
+`next-i18next` — це, мабуть, найпопулярніший варіант, оскільки він був одним із перших рішень i18n для JS-додатків. Він має багато плагінів від спільноти. Має ті ж основні недоліки, що й `next-intl`. Пакет особливо важкий (~18 КБ для `I18nProvider` + `useTranslation`, приблизно втричі більше за `next-intlayer`).
+
+Формати повідомлень також відрізняються: `next-intl` використовує ICU MessageFormat, тоді як `i18next` використовує власний формат.
+
+**(Next International)** (`next-international@1.3.1`):
+
+`next-international` також намагається вирішити ці проблеми, але не сильно відрізняється від `next-intl` або `next-i18next`. Він включає `scopedT()` для перекладів у межах просторів імен, але це практично не впливає на розмір бандла.
+
+**(Lingui)** (`@lingui/core@5.3.0`):
+
+`Lingui` часто хвалять. Особисто мені робочий процес із `lingui extract` / `lingui compile` здався складнішим за альтернативи, без явних переваг. Також помічені непослідовні синтаксиси, які плутають ШІ (наприклад, `t()`, `t''`, `i18n.t()`, `<Trans>`).
+
+### 4 — Рекомендації
+
+**(Next Translate)** (`next-translate@3.1.2`):
+
+`next-translate` — моя основна рекомендація, якщо вам подобається API у стилі `t()`. Він елегантно працює через `next-translate-plugin`, завантажуючи простори імен через `getStaticProps` за допомогою завантажувача Webpack / Turbopack. Це також найлегший варіант у цьому списку (~2.5 КБ). Визначення просторів імен для сторінок або маршрутів у конфігу добре продумане і простіше в підтримці, ніж у **next-intl** чи **next-i18next**. У версії `3.1.2` я помітив, що статичний рендеринг не працював; Next.js переходив до динамічного рендерингу.
+
+**(Intlayer)** (`next-intlayer@8.7.5`):
+
+Я не буду особисто оцінювати `next-intlayer` заради об’єктивності, оскільки це моє власне рішення.
+
+### Особиста замітка
+
+Ця замітка є особистою і не впливає на результати бенчмарку. Тим не менш, у світі i18n часто спостерігається консенсус навколо використання `const t = useTranslation('xx')` + `<>{t('xx.xx')}</>` для перекладеного контенту.
+
+У React-додатках передача функції як `ReactNode`, на мою думку, є антипатерном. Це також додає зайвої складності та накладних витрат на виконання JavaScript (навіть якщо це ледь помітно).

package/docs/uk/benchmark/tanstack.md

@@ -0,0 +1,193 @@
+---
+createdAt: 2026-04-20
+updatedAt: 2026-04-21
+title: Найкраще i18n рішення для TanStack Start у 2026 році - Звіт бенчмарку
+description: Порівняйте бібліотеки інтернаціоналізації для TanStack Start, такі як react-i18next, use-intl та Intlayer. Детальний звіт про продуктивність за розміром бандла, витоком та реактивністю.
+keywords:
+  - benchmark
+  - i18n
+  - intl
+  - tanstack
+  - продуктивність
+  - intlayer
+slugs:
+  - doc
+  - benchmark
+  - tanstack
+author: Aymeric PINEAU
+applicationTemplate: https://github.com/intlayer-org/benchmark-i18n-tanstack-start-template
+history:
+  - version: 8.7.5
+    date: 2026-01-06
+    changes: "Ініціалізація бенчмарку"
+---
+
+# Бібліотеки i18n для TanStack Start — Звіт бенчмарку 2026
+
+Ця сторінка є звітом бенчмарку i18n рішень на TanStack Start.
+
+## Зміст
+
+<Toc/>
+
+## Інтерактивний бенчмарк
+
+<I18nBenchmark framework="tanstack" vertical/>
+
+## Довідка за результатами:
+
+<iframe 
+  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;">
+</iframe>
+
+> https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-tanstack.md
+
+Дивіться повний репозиторій бенчмарку [тут](https://github.com/intlayer-org/benchmark-i18n/tree/main).
+
+## Вступ
+
+Рішення для інтернаціоналізації є одними з найважчих залежностей у React-додатках. У TanStack Start основний ризик полягає в передачі зайвого контенту: перекладів для інших сторінок та інших локалей у бандлі одного маршруту.
+
+У міру зростання додатку ця проблема може швидко роздути обсяг JavaScript, що надсилається клієнту, і сповільнити навігацію.
+
+На практиці для найменш оптимізованих реалізацій інтернаціоналізована сторінка може стати в кілька разів важчою за версію без i18n.
+
+Інший вплив стосується досвіду розробника (DX): як ви оголошуєте контент, типи, організація просторів імен, динамічне завантаження та реактивність при зміні мови.
+
+## Протестуйте свій додаток
+
+Щоб швидко виявити проблеми з витоком i18n, я налаштував безкоштовний сканер, доступний [тут](https://intlayer.org/i18n-seo-scanner).
+
+<iframe src="https://intlayer.org/i18n-seo-scanner" width="100%" height="600px" style="border:none;"/>
+
+## Проблема
+
+Два важелі є важливими для обмеження вартості багатомовного додатку:
+
+- Розділяйте контент за сторінками / просторами імен, щоб не завантажувати цілі словники, коли вони не потрібні.
+- Динамічно завантажуйте потрібну локаль лише тоді, коли це необхідно.
+
+Розуміння технічних обмежень цих підходів:
+
+**Динамічне завантаження**
+
+Без динамічного завантаження більшість рішень зберігають повідомлення в пам'яті з першого рендерингу, що додає значні накладні витрати для додатків з великою кількістю маршрутів та локалей.
+
+З динамічним завантаженням ви приймаєте компроміс: менше початкового JS, але іноді додатковий запит при зміні мови.
+
+**Розділення контенту (Content splitting)**
+
+Синтаксиси навколо `const t = useTranslation()` + `t('a.b.c')` дуже зручні, але часто заохочують зберігання великих JSON-об'єктів під час виконання (runtime). Така модель ускладнює видалення невикористаного коду (tree-shaking), якщо бібліотека не пропонує реальної стратегії розділення сторінок.
+
+## Методологія
+
+Для цього бенчмарку ми порівняли наступні бібліотеки:
+
+- `Base App` (Без бібліотеки i18n)
+- `react-intlayer` (v8.7.5-canary.0)
+- `react-i18next` (v17.0.2)
+- `use-intl` (v4.9.1)
+- `@lingui/core` (v5.3.0)
+- `@inlang/paraglide-js` (v2.15.1)
+- `tolgee` (v7.0.0)
+- `react-intl` (v10.1.1)
+- `wuchale` (v0.22.11)
+- `gt-react` (vlatest)
+- `lingo.dev` (v0.133.9)
+
+Фреймворк — `TanStack Start` з багатомовним додатком на **10 сторінок** та **10 мов**.
+
+Ми порівняли **чотири стратегії завантаження**:
+
+| Стратегія                  | Без просторів імен (global)                             | З просторами імен (scoped)                                                |
+| :------------------------- | :------------------------------------------------------ | :------------------------------------------------------------------------ |
+| **Статичне завантаження**  | **Static**: Все в пам'яті при запуску.                  | **Scoped static**: Розділено за простором імен; завантаження при запуску. |
+| **Динамічне завантаження** | **Dynamic**: Завантаження за запитом для кожної локалі. | **Scoped dynamic**: Гранулярне завантаження за простором імен та локаллю. |
+
+## Резюме стратегій
+
+- **Static**: Просто; відсутня мережева затримка після початкового завантаження. Мінус: великий розмір бандла.
+- **Dynamic**: Зменшує початкову вагу (lazy-loading). Ідеально, якщо у вас багато локалей.
+- **Scoped static**: Зберігає код структурованим (логічний поділ) без складних мережевих запитів.
+- **Scoped dynamic**: Найкращий підхід для _розділення коду_ (code splitting) та продуктивності. Мінімізує обсяг пам'яті, завантажуючи лише те, що потрібно поточному перегляду та активній локалі.
+
+## Детальні результати
+
+### 1 — Рішення, яких слід уникати
+
+Деяких рішень, таких як `gt-react` або `lingo.dev`, явно варто триматися подалі. Вони поєднують прив'язку до вендора із засміченням вашої кодової бази. Гірше того: попри багато годин спроб їх впровадження, я так і не зміг забезпечити їх коректну роботу на TanStack Start (аналогічно до `gt-next` на Next.js).
+
+Виявлені проблеми:
+
+**(General Translation)** (`gt-react@latest`):
+
+- Для додатку розміром близько 110 КБ `gt-react` може додати понад 440 КБ зайвих даних (порядок величини зафіксовано в реалізації Next.js у тому ж бенчмарку).
+- `Quota Exceeded, please upgrade your plan` вже під час першої збірки.
+- Переклади не рендериться; отримую помилку `Error: <T> used on the client-side outside of <GTProvider>`, що схоже на баг бібліотеки.
+- При впровадженні **gt-tanstack-start-react** я також стикнувся з [проблемою](https://github.com/generaltranslation/gt/issues/1210#event-24510646961) бібліотеки: помилка `does not provide an export named 'printAST' - @formatjs/icu-messageformat-parser`, через яку додаток падав. Після звіту про помилку розробник виправив її протягом 24 годин.
+- Ці бібліотеки використовують антипатерн через функцію `initializeGT()`, що заважає чистому видаленню невикористаного коду (tree-shaking) бандла.
+
+**(Lingo.dev)** (`lingo.dev@0.133.9`):
+
+- Перевищено квоту AI (або блокування серверної залежності), що робить збірку / продакшн ризикованим без оплати.
+- Компілятор пропустив майже 40% перекладеного контенту. Мені довелося переписувати всі `.map` у плоскі блоки компонентів, щоб це запрацювало.
+- Їхній CLI працює нестабільно і часто без причини скидає конфігураційний файл.
+- Під час збірки він повністю стирав згенеровані JSON-файли при додаванні нового контенту. У результаті лише кілька ключів могли знищити сотні наявних.
+- Я стикнувся з проблемами реактивності бібліотеки в TanStack Start: при зміні локалі довелося примусово перерендерити провайдер, щоб це запрацювало.
+
+### 2 — Експериментальні рішення
+
+**(Wuchale)** (`wuchale@0.22.11`):
+
+Ідея `Wuchale` цікава, але поки що не є життєздатним рішенням. Я зіткнувся з проблемами реактивності бібліотеки і був змушений примусово перерендерити провайдер, щоб додаток запрацював на TanStack Start. Документація також досить нечітка, що ускладнює освоєння.
+
+### 3 — Прийнятні рішення
+
+**(Paraglide)** (`@inlang/paraglide-js@2.15.1`):
+
+`Paraglide` пропонує інноваційний, добре продуманий підхід. Проте в цьому тесті рекламований компанією tree-shaking не спрацював ні для моєї реалізації на Next.js, ні для TanStack Start. Робочий процес і DX також складніші за інші варіанти. Особисто я не прихильник необхідності регенерувати JS-файли перед кожним пушем, що створює постійний ризик конфліктів під час злиття для розробників через PR.
+
+**(Tolgee)** (`tolgee@7.0.0`):
+
+`Tolgee` вирішує багато зі згаданих проблем. Проте почати роботу з ним здалося мені важче, ніж з іншими інструментами з подібними підходами. Він не забезпечує типізацію, що значно ускладнює виявлення відсутніх ключів під час компіляції. Мені довелося обертати Tolgee API своїми рішеннями, щоб додати перевірку відсутніх ключів.
+
+На TanStack Start я також мав проблеми з реактивністю: при зміні локалі довелося примусово перерендерити провайдер і підписуватися на події зміни локалі, щоб завантаження іншою мовою працювало коректно.
+
+**(use-intl)** (`use-intl@4.9.1`):
+
+`use-intl` — це зараз наймодніша частина "intl" в екосистемі React (та ж родина, що й `next-intl`), яку часто просувають ШІ-агенти, але на мій погляд — помилково в контексті продуктивності. Почати роботу досить просто. На практиці ж процес оптимізації та обмеження витоків є досить складним. Аналогічно, поєднання динамічного завантаження + просторів імен + типів TypeScript сильно сповільнює розробку.
+
+У TanStack Start ви уникаєте специфічних пасток Next.js (`setRequestLocale`, статичний рендеринг), але основна проблема та ж сама: без суворої дисципліни бандл швидко перевантажується повідомленнями, а підтримка просторів імен для кожного маршруту стає виснажливою.
+
+**(react-i18next)** (`react-i18next@17.0.2`):
+
+`react-i18next` — це, мабуть, найпопулярніший варіант, оскільки він був одним із перших, хто задовольнив потреби i18n у JS-додатках. Він також має великий набір плагінів від спільноти для конкретних проблем.
+
+Проте він має ті ж недоліки, що й стеки на базі `t('a.b.c')`: оптимізація можлива, але забирає багато часу, а великі проекти ризикують скотитися до поганих практик (простори імен + динамічне завантаження + типи).
+
+Формати повідомлень також відрізняються: `use-intl` використовує ICU MessageFormat, тоді як `i18next` має власний формат — це ускладнює інструментарій або міграцію, якщо ви їх змішуєте.
+
+**(Lingui)** (`@lingui/core@5.3.0`):
+
+`Lingui` часто хвалять. Особисто мені робочий процес із `lingui extract` / `lingui compile` здався складнішим за інші підходи, без явних переваг у цьому тесті TanStack Start. Також помічені непослідовні синтаксиси, які плутають ШІ (наприклад, `t()`, `t''`, `i18n.t()`, `<Trans>`).
+
+**(react-intl)** (`react-intl@10.1.1`):
+
+`react-intl` — це продуктивна реалізація від команди Format.js. DX залишається багатослівним: `const intl = useIntl()` + `intl.formatMessage({ id: "xx.xx" })` додає складності, додаткової роботи JavaScript та прив'язує глобальний екземпляр i18n до багатьох вузлів у React-дереві.
+
+### 4 — Рекомендації
+
+Цей бенчмарк TanStack Start не має прямого еквівалента `next-translate` (Next.js плагін + `getStaticProps`). Командам, які справді хочуть API у стилі `t()` зі зрілою екосистемою, `react-i18next` та `use-intl` залишаються "розумним" вибором, але будьте готові витратити багато часу на оптимізацію для уникнення витоків.
+
+**(Intlayer)** (`react-intlayer@8.7.5-canary.0`):
+
+Я не буду особисто оцінювати `react-intlayer` заради об’єктивності, оскільки це моє власне рішення.
+
+### Особиста замітка
+
+Ця замітка є особистою і не впливає на результати бенчмарку. Тим не менш, у світі i18n часто спостерігається консенсус навколо використання `const t = useTranslation('xx')` + `<>{t('xx.xx')}</>` для перекладеного контенту.
+
+У React-додатках передача функції як `ReactNode`, на мою думку, є антипатерном. Це також додає зайвої складності та накладних витрат на виконання JavaScript (навіть якщо це ледь помітно).

package/docs/vi/benchmark/index.md

@@ -0,0 +1,29 @@
+---
+createdAt: 2026-04-20
+updatedAt: 2026-04-20
+title: Điểm chuẩn các thư viện i18n
+description: Tìm hiểu cách Intlayer so sánh với các thư viện i18n khác về hiệu năng và kích thước gói bundle.
+keywords:
+  - benchmark
+  - i18n
+  - intl
+  - nextjs
+  - tanstack
+  - intlayer
+slugs:
+  - doc
+  - benchmark
+history:
+  - version: 8.7.5
+    date: 2026-01-06
+    changes: "Khởi tạo benchmark"
+---
+
+# Benchmark - Báo cáo
+
+Benchmark Bloom là bộ công cụ đo hiệu năng, đánh giá tác động thực tế của các thư viện i18n (quốc tế hóa) trên nhiều framework React và chiến lược tải.
+
+Báo cáo chi tiết và tài liệu kỹ thuật cho từng framework nằm bên dưới:
+
+- [**Báo cáo benchmark Next.js**](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/benchmark/nextjs.md)
+- [**Báo cáo benchmark TanStack Start**](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/benchmark/tanstack.md)