@intlayer/docs 8.7.5-canary.0 → 8.7.5

package/docs/ru/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-shake) неиспользуемый контент для конкретной страницы.
+- Динамическая загрузка контента страницы только на языке пользователя.
+
+Технические ограничения этих подходов:
+
+**Динамическая загрузка**
+
+Даже если вы объявляете маршруты типа `[locale]/page.tsx`, с Webpack или Turbopack, и даже если определен `generateStaticParams`, сборщик не рассматривает `locale` как статическую константу. Это означает, что он может включить контент для всех языков в каждую страницу. Основной способ ограничить это — загружать контент через динамический импорт (например, `import('./locales/${locale}.json')`).
+
+На этапе сборки Next.js создает один JS-бандл на локаль (например, `./locales_fr_12345.js`). Когда сайт отправляется клиенту и страница запускается, браузер выполняет дополнительный HTTP-запрос для необходимого JS-файла (например, `./locales_fr_12345.js`).
+
+> Другой способ решения той же проблемы — использование `fetch()` для динамической загрузки JSON. Так работает `Tolgee`, когда JSON находится в `/public`, или `next-translate`, который полагается на `getStaticProps` для загрузки контента. Процесс тот же: браузер делает дополнительный HTTP-запрос для загрузки ресурса.
+
+**Разделение контента**
+
+Если вы используете синтаксис типа `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 языками**.
+
+Я сравнил **четыре стратегии загрузки**:
+
+| Стратегия                 | Без пространств имен (глобальная)               | С пространствами имен (локальная/scoped)                                         |
+| :------------------------ | :---------------------------------------------- | :------------------------------------------------------------------------------- |
+| **Статическая загрузка**  | **Static**: Все в памяти при запуске.           | **Scoped static**: Разделено по пространствам имен; все загружается при запуске. |
+| **Динамическая загрузка** | **Dynamic**: Загрузка по требованию для локали. | **Scoped dynamic**: Гранулярная загрузка по пространствам имен и локалям.        |
+
+## Резюме стратегий
+
+- **Статическая (Static)**: Простота; отсутствие задержек сети после начальной загрузки. Минус: большой размер бандла.
+- **Динамическая (Dynamic)**: Уменьшает начальный вес (ленивая загрузка). Идеально при наличии множества локалей.
+- **Локальная статическая (Scoped static)**: Позволяет организовать код (логическое разделение) без сложных дополнительных сетевых запросов.
+- **Локальная динамическая (Scoped dynamic)**: Лучший подход для _разделения кода_ и производительности. Минимизирует использование памяти, загружая только то, что нужно для текущего представления и активной локали.
+
+### Что я измерял:
+
+Я запускал одно и то же мультиязычное приложение в реальном браузере для каждого стека, а затем записывал, что на самом деле передавалось по сети и сколько времени это занимало. Размеры указаны **после обычного веб-сжатия**, так как это ближе к тому, что скачивают пользователи, чем количество исходного кода.
+
+- **Размер библиотеки интернационализации**: После сборки, tree-shaking и минимизации, размер i18n-библиотеки — это размер провайдеров (например, `NextIntlClientProvider`) + код хуков (например, `useTranslations`) в пустом компоненте. Это не включает загрузку файлов перевода. Это ответ на вопрос, насколько "дорогая" библиотека сама по себе до добавления вашего контента.
+
+- **JavaScript на страницу**: Для каждого маршрута бенчмарка — сколько скриптов браузер загружает при посещении, усредненное по страницам в наборе (и по локалям, где отчет их объединяет). Тяжелые страницы — это медленные страницы.
+
+- **Утечка из других локалей**: Это контент той же страницы, но на другом языке, который ошибочно загружается на проверяемую страницу. Этого контента следует избегать (например, контент страницы `/fr/about` в бандле страницы `/en/about`).
+
+- **Утечка из других маршрутов**: Та же идея для **других экранов** в приложении: попадает ли их текст в сборку, когда вы открыли только одну страницу (например, контент страницы `/en/about` в бандле страницы `/en/contact`). Высокий показатель указывает на плохое разделение или слишком широкие бандлы.
+
+- **Средний размер бандла компонента**: Общие элементы пользовательского интерфейса измеряются **по отдельности**, а не прячутся внутри одного гигантского числа приложения. Это показывает, не раздувает ли интернационализация обычные компоненты. Например, если ваш компонент перерендеривается, он будет загружать все эти данные из памяти. Привязка гигантского JSON-файла к любому компоненту подобна подключению большого хранилища неиспользуемых данных, которое замедлит работу ваших компонентов.
+
+- **Скорость переключения языка**: Я переключаю язык с помощью собственного элемента управления приложения и засекаю время, пока страница явно не переключится — то, что заметит посетитель, а не лабораторный микро-шаг.
+
+- **Работа по рендерингу после смены языка**: Более узкое наблюдение: сколько усилий потребовалось интерфейсу для перерисовки на новом языке после начала переключения. Полезно, когда "ощущаемое" время и стоимость фреймворка расходятся.
+
+- **Время начальной загрузки страницы**: От перехода до того момента, когда браузер считает страницу полностью загруженной для протестированных сценариев. Хорошо для сравнения "холодных стартов".
+
+- **Время гидратации**: Когда приложение предоставляет такие данные — сколько времени клиент тратит на превращение серверного HTML в нечто, на что можно нажать. Прочерк в таблицах означает, что данная реализация не предоставила надежных данных по гидратации в этом бенчмарке.
+
+## Результаты в деталях
+
+### 1 — Решения, которых следует избегать
+
+Некоторых решений, таких как `gt-next` или `lingo.dev`, явно лучше избегать. Они сочетают в себе привязку к вендору с загрязнением вашей кодовой базы. Несмотря на многие часы попыток их внедрить, мне так и не удалось заставить их работать — ни на TanStack Start, ни на Next.js.
+
+Встреченные проблемы:
+
+**(General Translation)** (`gt-next@6.16.5`):
+
+- Для приложения весом 110 КБ `gt-react` добавляет более 440 КБ сверху.
+- `Quota Exceeded, please upgrade your plan` (Квота превышена, пожалуйста, обновите тарифный план) при самой первой сборке с General Translation.
+- Переводы не отображаются; я получаю ошибку `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 / куки и т.д. Это приводит к выполнению ненужной логики, которая влияет на реактивность компонентов.
+
+### 3 — Приемлемые решения
+
+**(Tolgee)** (`tolgee@7.0.0`):
+
+`Tolgee` решает многие из упомянутых ранее проблем. Мне показалось, что его сложнее внедрить, чем аналогичные инструменты. Он не обеспечивает типобезопасность, что также затрудняет отлов отсутствующих ключей на этапе компиляции. Мне пришлось обернуть функции Tolgee своими собственными, чтобы добавить обнаружение отсутствующих ключей.
+
+**(Next Intl)** (`next-intl@4.9.1`):
+
+`next-intl` — самый модный вариант, который чаще всего продвигают AI-агенты, но, на мой взгляд, ошибочно. Начать работу легко. На практике оптимизация для ограничения утечек сложна. Сочетание динамической загрузки + пространств имен + типов TypeScript сильно замедляет разработку. Пакет также довольно тяжелый (~13 КБ для `NextIntlClientProvider` + `useTranslations`, что более чем в 2 раза больше `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-решений для JavaScript-приложений. У него много плагинов от сообщества. У него те же основные недостатки, что и у `next-intl`. Пакет особенно тяжелый (~18 КБ для `I18nProvider` + `useTranslation`, примерно в 3 раза тяжелее `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` показался более сложным, чем у альтернатив, без явных преимуществ. Я также заметил непоследовательный синтаксис, который путает AI (например, `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/ru/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.
+
+Другой аспект — это опыт разработчика: то, как вы объявляете контент, типы, организацию пространств имен, динамическую загрузку и реактивность при смене локали.
+
+## Проверьте свое приложение
+
+Чтобы быстро выявить проблемы с утечкой i18n, я настроил бесплатный сканер, доступный [здесь](https://intlayer.org/i18n-seo-scanner).
+
+<iframe src="https://intlayer.org/i18n-seo-scanner" width="100%" height="600px" style="border:none;"/>
+
+## Проблема
+
+Два рычага необходимы для ограничения стоимости мультиязычного приложения:
+
+- Разделение контента по страницам / пространствам имен, чтобы не загружать целые словари, когда они вам не нужны.
+- Динамическая загрузка нужной локали только тогда, когда она требуется.
+
+Понимание технических ограничений этих подходов:
+
+**Динамическая загрузка**
+
+Без динамической загрузки большинство решений хранят сообщения в памяти с первого рендеринга, что создает значительные накладные расходы для приложений с множеством маршрутов и локалей.
+
+При использовании динамической загрузки вы идете на компромисс: меньше начального JS, но иногда дополнительный запрос при переключении языка.
+
+**Разделение контента**
+
+Синтаксис, построенный вокруг `const t = useTranslation()` + `t('a.b.c')`, очень удобен, но часто способствует хранению больших JSON-объектов во время выполнения. Эта модель затрудняет 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 языков**.
+
+Мы сравнили **четыре стратегии загрузки**:
+
+| Стратегия                 | Без пространств имен (глобальная)               | С пространствами имен (локальная/scoped)                                         |
+| :------------------------ | :---------------------------------------------- | :------------------------------------------------------------------------------- |
+| **Статическая загрузка**  | **Static**: Все в памяти при запуске.           | **Scoped static**: Разделено по пространствам имен; все загружается при запуске. |
+| **Динамическая загрузка** | **Dynamic**: Загрузка по требованию для локали. | **Scoped dynamic**: Гранулярная загрузка по пространствам имен и локалям.        |
+
+## Резюме стратегий
+
+- **Статическая (Static)**: Простота; отсутствие задержек сети после начальной загрузки. Минус: большой размер бандла.
+- **Динамическая (Dynamic)**: Уменьшает начальный вес (ленивая загрузка). Идеально при наличии множества локалей.
+- **Локальная статическая (Scoped static)**: Позволяет организовать код (логическое разделение) без сложных дополнительных сетевых запросов.
+- **Локальная динамическая (Scoped dynamic)**: Лучший подход для _разделения кода_ и производительности. Минимизирует использование памяти, загружая только то, что нужно для текущего представления и активной локали.
+
+## Результаты в деталях
+
+### 1 — Решения, которых следует избегать
+
+Некоторых решений, таких как `gt-react` или `lingo.dev`, явно стоит остерегаться. Они сочетают в себе привязку к вендору с загрязнением вашей кодовой базы. Хуже того: несмотря на многие часы попыток внедрить их, мне так и не удалось заставить их работать должным образом на TanStack Start (аналогично Next.js с `gt-next`).
+
+Встреченные проблемы:
+
+**(General Translation)** (`gt-react@latest`):
+
+- Для приложения весом около 110 КБ `gt-react` может добавить более 440 КБ сверху (порядок величины, наблюдаемый в реализации Next.js в том же бенчмарке).
+- `Quota Exceeded, please upgrade your plan` (Квота превышена, пожалуйста, обновите тарифный план) при самой первой сборке с General Translation.
+- Переводы не отображаются; я получаю ошибку `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` решает многие из упомянутых ранее проблем. Мне показалось, что начать работу с ним сложнее, чем с другими инструментами с похожими подходами. Он не обеспечивает типобезопасность, что значительно затрудняет отлов отсутствующих ключей на этапе компиляции. Мне пришлось обернуть API Tolgee своими собственными, чтобы добавить обнаружение отсутствующих ключей.
+
+На TanStack Start у меня также были проблемы с реактивностью: при смене локали мне приходилось принудительно перерендеривать провайдер и подписываться на события смены локали, чтобы загрузка на другом языке вела себя корректно.
+
+**(use-intl)** (`use-intl@4.9.1`):
+
+`use-intl` — самый модный представитель "intl" в экосистеме React (из того же семейства, что и `next-intl`), который часто продвигают AI-агенты, но, на мой взгляд, ошибочно в контексте производительности. Начать работу довольно просто. На практике процесс оптимизации и ограничения утечек довольно сложен. Аналогично, сочетание динамической загрузки + пространств имен + типов TypeScript сильно замедляет разработку.
+
+На TanStack Start вы избегаете ловушек, специфичных для Next.js (`setRequestLocale`, статический рендеринг), но основная проблема та же: без строгой дисциплины бандл быстро переполняется сообщениями, а обслуживание пространств имен для каждого маршрута становится мучительным.
+
+**(react-i18next)** (`react-i18next@17.0.2`):
+
+`react-i18next`, вероятно, является самым популярным вариантом, так как был одним из первых решений для нужд i18n в JavaScript-приложениях. У него также есть широкий набор плагинов от сообщества для конкретных задач.
+
+Тем не менее, у него те же основные недостатки, что и у стеков, построенных на `t('a.b.c')`: оптимизация возможна, но отнимает очень много времени, а большие проекты рискуют столкнуться с плохими практиками.
+
+Форматы сообщений также расходятся: `use-intl` использует ICU MessageFormat, в то время как `i18next` использует свой собственный формат, что усложняет инструментарий или миграцию при их смешивании.
+
+**(Lingui)** (`@lingui/core@5.3.0`):
+
+`Lingui` часто хвалят. Лично мне рабочий процесс вокруг `lingui extract` / `lingui compile` показался более сложным, чем другие подходы, без явных преимуществ в этом бенчмарке TanStack Start. Я также заметил непоследовательный синтаксис, который путает AI (например, `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/tr/benchmark/index.md

@@ -0,0 +1,29 @@
+---
+createdAt: 2026-04-20
+updatedAt: 2026-04-20
+title: i18n Kütüphaneleri Karşılaştırması (Benchmark)
+description: Intlayer'ın performans ve paket boyutu açısından diğer i18n kütüphaneleriyle nasıl karşılaştırıldığını öğrenin.
+keywords:
+  - benchmark
+  - i18n
+  - intl
+  - nextjs
+  - tanstack
+  - intlayer
+slugs:
+  - doc
+  - benchmark
+history:
+  - version: 8.7.5
+    date: 2026-01-06
+    changes: "Benchmark başlatıldı"
+---
+
+# Benchmark - Rapor
+
+Benchmark Bloom, birden fazla React çatısı ve yükleme stratejisinde i18n (uluslararasılaştırma) kütüphanelerinin gerçek dünyadaki etkisini ölçen bir performans kıyaslama paketidir.
+
+Her çatı için ayrıntılı raporlar ve teknik belgeleri aşağıda bulabilirsiniz:
+
+- [**Next.js benchmark raporu**](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/benchmark/nextjs.md)
+- [**TanStack Start benchmark raporu**](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/benchmark/tanstack.md)