@intlayer/docs 9.4.4 → 9.5.0

package/blog/ru/react-i18next_vs_react-intl_vs_intlayer.md

@@ -35,16 +35,12 @@ author: aymericzip
 
 > **Кратко**: Все три решения могут локализовать React-приложение. Если вам нужен **контент, ограниченный компонентом**, **строгая типизация TypeScript**, **проверка отсутствующих ключей во время сборки**, **деревья сжатых словарей** и встроенные редакторские инструменты (Визуальный редактор/CMS + опциональный AI-перевод), то **Intlayer** - самый полный выбор для модульных React-кодовых баз.
 
----
-
 ## Общее позиционирование
 
 - **react-intl** - форматирование, ориентированное на ICU и соответствующее стандартам (даты/числа/множественное число) с зрелым API. Каталоги обычно централизованы; безопасность ключей и проверка во время сборки в основном на вашей стороне.
 - **react-i18next** - чрезвычайно популярный и гибкий; пространства имён, детекторы и множество плагинов (ICU, бекенды). Мощный, но конфигурация может разрастаться по мере масштабирования проектов.
 - **Intlayer** - модель контента, ориентированная на компоненты React, **строгая типизация TS**, **проверки во время сборки**, **tree-shaking**, а также **Визуальный редактор/CMS** и **переводы с помощью ИИ**. Работает с React Router, Vite, CRA и др.
 
----
-
 ## Матрица возможностей (фокус на React)
 
 | Особенность                                               | `react-intlayer` (Intlayer)                                                                                                                         | `react-i18next` (i18next)                                                                                                        | `react-intl` (FormatJS)                                                                                       |
@@ -69,8 +65,6 @@ author: aymericzip
 | **Удаление неиспользуемого контента**                     | ✅ Да, по словарям во время сборки                                                                                                                  | ❌ Нет, только через ручное разделение по неймспейсам                                                                            | ❌ Нет, все объявленные сообщения включены в пакет                                                            |
 | **Управление крупными проектами**                         | ✅ Поощряет модульность, подходит для дизайн-систем                                                                                                 | ⚠️ Требует хорошей дисциплины в работе с файлами                                                                                 | ⚠️ Центральные каталоги могут стать большими                                                                  |
 
----
-
 ## Глубокое сравнение
 
 ### 1) Архитектура и масштабируемость
@@ -80,8 +74,6 @@ author: aymericzip
 
 **Почему это важно:** Модульный контент отражает модульный UI. Большие React-кодовые базы остаются чище, когда переводы живут вместе с компонентами, которым они принадлежат.
 
----
-
 ### 2) TypeScript и безопасность
 
 - **react-intl**: Надежные типы, но **нет автоматической типизации ключей**; вы сами обеспечиваете паттерны безопасности.
@@ -90,8 +82,6 @@ author: aymericzip
 
 **Почему это важно:** Перемещение ошибок **влево** (на этап сборки/CI) снижает количество проблем в продакшене и ускоряет цикл обратной связи для разработчиков.
 
----
-
 ### 3) Обработка отсутствующих переводов
 
 - **react-intl / react-i18next**: По умолчанию используют **запасные варианты во время выполнения** (отображение ключа или локаль по умолчанию). Можно добавить линтеры/плагины, но гарантий на этапе сборки нет.
@@ -99,8 +89,6 @@ author: aymericzip
 
 **Почему это важно:** Сбой CI из-за отсутствующих строк предотвращает появление «загадочного английского» в неанглоязычных интерфейсах.
 
----
-
 ### 4) Богатый контент и форматирование
 
 - **react-intl**: Отличная поддержка **ICU** для множественного числа, выборов, дат/чисел и составления сообщений. Можно использовать JSX, но ментальная модель остается ориентированной на сообщения.
@@ -109,8 +97,6 @@ author: aymericzip
 
 **Почему это важно:** Сложные тексты UI (ссылки, выделенные части, встроенные компоненты) проще реализовать, когда библиотека чисто поддерживает React-узлы.
 
----
-
 ### 5) Производительность и поведение загрузки
 
 - **react-intl / react-i18next**: Обычно вы самостоятельно управляете **разделением каталогов** и **ленивой загрузкой** (пространства имён/динамические импорты). Эффективно, но требует дисциплины.
@@ -118,8 +104,6 @@ author: aymericzip
 
 **Почему это важно:** Меньшие бандлы и меньше неиспользуемых строк улучшают производительность запуска и навигации.
 
----
-
 ### 6) DX, инструменты и сопровождение
 
 - **react-intl / react-i18next**: Широкая экосистема сообщества; для редакционных рабочих процессов обычно используют внешние платформы локализации.
@@ -127,24 +111,18 @@ author: aymericzip
 
 **Почему это важно:** Встроенные инструменты сокращают цикл взаимодействия между разработчиками и авторами контента - меньше вспомогательного кода, меньше зависимостей от сторонних поставщиков.
 
----
-
 ## Когда что выбирать?
 
 - **Выбирайте react-intl**, если вам нужен **ICU-первый** формат сообщений с простым, соответствующим стандартам API, и ваша команда готова вручную поддерживать каталоги и проверки безопасности.
 - **Выбирайте react-i18next**, если вам нужна **широкая экосистема i18next** (детекторы, бэкенды, плагин ICU, интеграции) и вы готовы к большей конфигурации ради гибкости.
 - **Выбирайте Intlayer**, если вы цените **контент, ограниченный компонентом**, **строгую типизацию TypeScript**, **гарантии на этапе сборки**, **tree-shaking** и **встроенные инструменты редактирования** - особенно для **больших, модульных** React-приложений.
 
----
-
 ## Взаимодействие с `react-intl` и `react-i18next`
 
 `intlayer` также может помочь управлять вашими пространствами имен `react-intl` и `react-i18next`.
 
 Используя `intlayer`, вы можете объявлять свой контент в формате вашей любимой библиотеки i18n, и intlayer будет генерировать ваши пространства имен в выбранном вами месте (пример: `/messages/{{locale}}/{{namespace}}.json`).
 
----
-
 ## Практические заметки по миграции (react-intl / react-i18next → Intlayer)
 
 - **Мигрируйте постепенно**: начните с одной функции или маршрута; в период перехода сохраняйте старые каталоги параллельно.
@@ -152,8 +130,6 @@ author: aymericzip
 - **Включите строгие проверки**: позволяйте ошибкам на этапе сборки выявлять отсутствующие ключи/локали на ранних этапах CI.
 - **Измеряйте размер бандлов**: ожидайте уменьшения размера по мере удаления неиспользуемых строк.
 
----
-
 ## Заключение
 
 Все три библиотеки эффективно локализуют React. Главное отличие - сколько **инфраструктуры** вам нужно построить, чтобы получить **безопасную, масштабируемую** систему:

package/blog/ru/transform_existing_nextjs_app_using_compiler.md

@@ -0,0 +1,293 @@
+---
+createdAt: 2026-01-10
+updatedAt: 2026-09-06
+title: "Как постфактум сделать существующее приложение Next.js многоязычным (i18n руководство 2026)"
+description: "Руководство 2026 года по добавлению многоязычности (i18n) в существующее приложение Next.js без утомительного рефакторинга. Автоматическое извлечение, ИИ-перевод и маршрутизация с Intlayer."
+keywords:
+  - Next.js i18n
+  - Интернационализация
+  - Перевести существующее приложение Next.js
+  - Next.js 16
+  - Intlayer
+  - Многоязычность
+  - React i18n
+  - Компилятор
+  - ИИ-перевод
+  - SEO
+slugs:
+  - blog
+  - transform-existing-nextjs-app-into-multilingual-app
+applicationTemplate: https://github.com/aymericzip/intlayer-next-no-lolale-path-template
+youtubeVideo: https://www.youtube.com/watch?v=e_PPG7PTqGU
+history:
+  - version: 9.4.0
+    date: 2026-08-22
+    changes: "Update to Next.js >= 9.4.0 architecture"
+  - version: 8.9.0
+    date: 2026-05-04
+    changes: "Update Solid useIntlayer API usage to direct property access"
+  - version: 8.2.0
+    date: 2026-03-09
+    changes: "Update compiler options, add FilePathPattern support"
+  - version: 8.1.6
+    date: 2026-02-23
+    changes: "Initial release"
+author: aymericzip
+---
+
+# Как постфактум сделать существующее приложение Next.js многоязычным (i18n руководство 2026)
+
+Добавить интернационализацию (i18n) в проект Next.js с самого начала относительно просто. Но что делать, если у вас уже есть готовое production-приложение на одном языке, и вам нужно сделать его мультиязычным **постфактум**?
+
+С традиционными библиотеками (`next-intl`, `next-i18next`) это превращается в кошмар:
+
+- Поиск захардкоженных строк в сотнях файлов JSX/TSX.
+- Создание вложенных JSON-словарей и придумывание ключей перевода (`pages.dashboard.header.title`).
+- Замена текста на громоздкие вызовы хуков (`t('...')`).
+- Перенос всей папки `app/` в `app/[locale]/...`, что ломает существующие маршруты и SEO.
+
+В 2026 году вам больше не нужно переписывать проект. С **Intlayer** вы можете локализовать существующее приложение Next.js за считанные минуты благодаря автоматическому извлечению, переводу с помощью ИИ и гибкой маршрутизации.
+
+> Ищете подробное пошаговое руководство для Next.js 16 App Router? Ознакомьтесь с документацией: [Локализация Next.js 16 с Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_with_nextjs_16.md).
+
+## Содержание
+
+<TOC/>
+
+## Дилемма доработки: почему локализация готового приложения трудна
+
+Разработчики сталкиваются с тремя сложностями:
+
+1. **Нарушение кодовой базы**: Ручной перенос текста в JSON требует правок почти во всех компонентах.
+2. **Ограничения маршрутизации**: Необходимость переносить код в динамический сегмент `[locale]`.
+3. **Рутинный перевод**: Копирование и перевод строк на 5-20 языков вручную.
+
+Intlayer решает эти проблемы с помощью **компилятора**, **декларативных словарей** и **гибкого роутинга**.
+
+## Автоматическое извлечение контента (без ручного поиска)
+
+### Вариант A: CLI-утилита извлечения (`npx intlayer extract`)
+
+Запустите утилиту извлечения прямо в вашем проекте:
+
+```bash packageManager="npm"
+npx intlayer extract
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer extract
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer extract
+```
+
+```bash packageManager="bun"
+bunx intlayer extract
+```
+
+Команда создаст типизированные декларации (`.content.ts`) рядом с каждым компонентом.
+
+### Вариант B: Компилятор Intlayer (Извлечение во время сборки)
+
+Пишите обычный текст в компонентах. Компилятор сам извлечет его при сборке и подставит локализованные данные:
+
+```tsx fileName="src/app/page.tsx"
+// Write normal React code. The compiler extracts the text automatically
+export default function HomePage() {
+  return (
+    <section>
+      <h1>Welcome to our platform</h1>
+      <p>Start exploring our modern features today.</p>
+    </section>
+  );
+}
+```
+
+Под капотом Intlayer создает словарь и связывает компонент с локализованным контентом, полностью исключая необходимость ручного рефакторинга.
+
+В этом случае будет сгенерирован файл `src/app/page.content.ts` со следующим содержимым:
+
+```typescript fileName="src/app/page.content.ts"
+import { Dictionary } from "intlayer";
+
+const content = {
+  key: "home-page",
+  content: {
+    welcomeToOurPlatform: t({ en: "Welcome to our platform" }),
+    startExploringOurModernFeaturesToday: t({
+      en: "Start exploring our modern features today.",
+    }),
+  },
+};
+
+export default content;
+```
+
+## ИИ-перевод с вашей любимой языковой моделью
+
+Переводите контент за секунды с помощью OpenAI, Anthropic, DeepSeek или Mistral:
+
+```bash packageManager="npm"
+npx intlayer fill
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer fill
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer fill
+```
+
+```bash packageManager="bun"
+bunx intlayer fill
+```
+
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH, Locales.GERMAN],
+    defaultLocale: Locales.ENGLISH,
+  },
+  ai: {
+    provider: "openai",
+    model: "gpt-4o-mini",
+    apiKey: process.env.OPENAI_API_KEY,
+    applicationContext: "SaaS панель для продуктивности и совместной работы",
+  },
+};
+
+export default config;
+```
+
+Команда `npx intlayer fill` автоматически заполнит переводами для всех настроенных локалей ваши декларации `.content.ts`:
+
+```typescript fileName="src/app/page.content.ts"
+import { Dictionary } from "intlayer";
+
+const content = {
+  key: "home-page",
+  content: {
+    welcomeToOurPlatform: t({
+      en: "Welcome to our platform",
+      fr: "Bienvenue sur notre plateforme",
+      es: "Bienvenido a nuestra plataforma",
+      ru: "Добро пожаловать на нашу платформу",
+    }),
+    startExploringOurModernFeaturesToday: t({
+      en: "Start exploring our modern features today.",
+      fr: "Découvrez nos fonctionnalités modernes dès aujourd'hui.",
+      es: "Comience a explorar nuestras funciones modernas hoy.",
+      ru: "Начните использовать современные функции уже сегодня.",
+    }),
+  },
+};
+
+export default content;
+```
+
+Поскольку Intlayer передает высокоуровневый `applicationContext` в LLM, сгенерированные переводы сохраняют технические нюансы, голос бренда и грамматический контекст намного лучше, чем традиционные инструменты машинного перевода.
+
+Чтобы убедиться, что ни одна строка не пропущена перед отправкой в продакшен:
+
+```bash
+npx intlayer test
+```
+
+## Мультиязычная маршрутизация без смены URL
+
+Intlayer поддерживает:
+
+- **Параметры запроса / Cookies (`search-params`)**: Сохраняйте структуру `/app/page.tsx` без создания папки `[locale]`.
+- **Префиксный режим (`prefix` / `prefix-all-locales`)**: Простая настройка префиксов для SEO.
+
+Настройте интеграцию с Next.js за считанные секунды:
+
+```typescript fileName="next.config.ts"
+import type { NextConfig } from "next";
+import { withIntlayer } from "next-intlayer/server";
+
+const nextConfig: NextConfig = {/* Your existing Next.js config */};
+
+export default withIntlayer(nextConfig);
+```
+
+Оберните корневой layout в `IntlayerProvider`:
+
+```tsx fileName="src/app/layout.tsx"
+import type { ReactNode } from "react";
+import { IntlayerProvider } from "next-intlayer";
+import { getLocale } from "next-intlayer/server";
+import { getHTMLTextDir } from "intlayer";
+
+export default async function RootLayout({
+  children,
+}: {
+  children: ReactNode;
+}) {
+  const locale = await getLocale();
+
+  return (
+    <html lang={locale} dir={getHTMLTextDir(locale)}>
+      <body>
+        <IntlayerProvider defaultLocale={locale}>{children}</IntlayerProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+## Мультиязычный SEO
+
+Автоматически генерируйте локализованные метаданные и теги `hreflang` для глобальной видимости:
+
+```tsx fileName="src/app/page.tsx"
+import type { Metadata } from "next";
+import { getLocale } from "next-intlayer/server";
+import { getIntlayer } from "intlayer";
+
+export const generateMetadata = async (): Promise<Metadata> => {
+  const locale = await getLocale();
+  const content = getIntlayer("home-page-metadata", locale);
+
+  return {
+    title: content.title,
+    description: content.description,
+  };
+};
+```
+
+## Подробный разбор: готовы к пошаговой настройке?
+
+Полная техническая документация с примерами middleware, SSG (`generateStaticParams`) и Server Components доступна в руководстве:
+
+👉 **[Полное руководство по локализации Next.js 16 с Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_with_nextjs_16.md)**
+
+## Часто задаваемые вопросы (FAQ)
+
+<FAQ>
+
+<Question title="Можно ли сделать приложение мультиязычным без переноса в app/[locale]?">
+
+Да. Intlayer поддерживает режим `search-params` и определение языка по cookies/заголовкам без изменения структуры папок.
+
+</Question>
+<Question title="Нужно ли вручную заменять все строки в проекте?">
+
+Нет. Утилита `npx intlayer extract` или компилятор Intlayer автоматически извлекают текст.
+
+</Question>
+<Question title="Почему бандл Intlayer меньше, чем у next-intl?">
+
+Благодаря модульной декларации по компонентам и макро-оптимизации во время сборки.
+
+</Question>
+<Question title="Можно ли использовать ИИ для перевода существующих компонентов?">
+
+Да, команда `npx intlayer fill` использует LLM для контекстного перевода на любые языки.
+
+</Question>
+</FAQ>