Миграция с react-i18next / i18next на Intlayer

Почему стоит перейти с react-i18next / i18next на Intlayer?

Стратегии миграции

Существует две дополняющие друг друга стратегии миграции с react-i18next / i18next на Intlayer:

1. Адаптер совместимости (рекомендуется для существующих приложений) — Установите @intlayer/react-i18next (для компонентов React) и/или @intlayer/i18next (для корневого инстанса i18n). Эти пакеты предоставляют абсолютно тот же API, что и react-i18next / i18next, но перенаправляют всю логику переводов в Intlayer. Ваши текущие вызовы useTranslation, Trans, withTranslation, i18next.t() остаются нетронутыми — изменяется только путь импорта.

2. Полная миграция — Постепенно заменяйте API react-i18next на нативные хуки Intlayer (useIntlayer, IntlayerProvider) и переводите ваш контент в файлы .content.ts, размещая их рядом с компонентами.

В этом руководстве сначала рассматривается Стратегия 1 (адаптер совместимости), а затем — опциональная полная миграция.

Оглавление

Быстрая миграция

Следующие шаги — это необходимый минимум для запуска вашего приложения react-i18next с Intlayer без изменений в коде компонентов.

1. 1

   Установка зависимостей

   Установите основные пакеты Intlayer и адаптер совместимости:

   bash

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   npm install intlayer react-intlayer @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-pluginnpx intlayer init

   Вы можете смело оставить установленными react-i18next и i18next — адаптер совместимости использует их как devDependencies / peerDependencies для типов TypeScript. Вам не нужно удалять какие-либо peer зависимости в package.json.

2. 2

   Настройка Intlayer

   Команда intlayer init создает базовый файл intlayer.config.ts. Обновите его, указав ваши текущие локали, и настройте плагин syncJSON на ваши файлы сообщений:

   intlayer.config.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import { Locales, type IntlayerConfig } from "intlayer";
   import { syncJSON } from "@intlayer/sync-json-plugin";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // Добавьте все ваши текущие локали сюда
       ],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         // соответствует синтаксису плейсхолдеров react-i18next: {{name}}
         format: "i18next",
         source: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/locales",
       }),
     ],
   };
   
   export default config;

   source сопоставляет локаль с путем к соответствующему JSON-файлу. location сообщает вотчеру (watcher) Intlayer, за какой папкой нужно следить для отслеживания изменений. Настройка format: 'i18next' гарантирует правильную обработку плейсхолдеров вроде {{name}}.

3. 3

   Добавление плагинов Intlayer в сборщик

   Оберните вашу текущую конфигурацию сборщика плагином совместимости. Это подключает базовый плагин Intlayer, включает отслеживание контента и, что самое важное, внедряет алиасы модулей, так что во время сборки все импорты import … from 'react-i18next' (и 'i18next') прозрачно перенаправляются на @intlayer/react-i18next / @intlayer/i18next. Никаких изменений в исходном коде не требуется.

   Для Vite:

   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() оборачивает плагин intlayer() из vite-intlayer и автоматически добавляет алиасы для react-i18next / i18next. Использование обычного плагина intlayer() из vite-intlayer скомпилирует словари, но не добавит алиасы — в таком случае вам придется вручную переименовать импорты в @intlayer/* (см. шаг 4).

   Для Next.js:

   Если вы используете next-i18next (Pages Router интеграция), установите @intlayer/next-i18next и next-intlayer:

   bash

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   npm install @intlayer/next-i18next next-intlayer

   Затем добавьте плагин совместимости в ваш next.config.ts (он внедрит алиасы для next-i18next / react-i18next / i18next):

   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);

   Вызов i18next.init() или ручная загрузка провайдеров больше не требуются. Intlayer компилирует все словари на этапе сборки (build-time), удаляя шаг загрузки "на лету" (runtime). Подмененный Provider заботится об инициализации.

На этом быстрая миграция завершена. Теперь ваше приложение работает на Intlayer, при этом все ваши импорты и API react-i18next остаются нетронутыми.

Строгая типизация ключей перевода — автоматически. Как только Intlayer скомпилирует словари, useTranslation и getFixedT будут типизированы на основе вашего реального контента. Ключи будут автодополняться в вашей IDE, а недействительные пути приведут к ошибкам TypeScript при компиляции — дополнительная настройка не требуется.

tsx

Копировать содержимое

Копировать код

Копировать код в буфер обмена

// 'about' — зарегистрированный ключ словаря → t() принимает только валидные путиconst { t } = useTranslation("about");t("counter.label"); // ✓ автодополнениеt("does.not.exist"); // ✗ Ошибка TypeScript// На стороне сервера (инстанс i18next)const tAbout = i18n.getFixedT(null, "about");tAbout("counter.label"); // ✓ типизация

Полная миграция

Следующие шаги необязательны и могут выполняться постепенно. Они открывают доступ ко всему набору функций Intlayer: визуальному редактору, CMS, строго типизированным файлам контента, ИИ-автоматизации переводов и многому другому.

1. 4

   Явное переименование импортов (Опционально)

   Необязательно

   Плагин Intlayer уже справляется с подменой алиасов на уровне сборщика. Если вы хотите сделать зависимости явными в ваших исходных файлах, вы можете переименовать импорты вручную:

   Показать все данные таблицы

   Показать все данные таблицы

   Открыть таблицу в модальном окне для четкого просмотра всех данных

   Было	Стало
   import { useTranslation } from 'react-i18next'	import { useTranslation } from '@intlayer/react-i18next'
   import { Trans } from 'react-i18next'	import { Trans } from '@intlayer/react-i18next'
   import { withTranslation } from 'react-i18next'	import { withTranslation } from '@intlayer/react-i18next'
   import { I18nextProvider } from 'react-i18next'	import { I18nextProvider } from '@intlayer/react-i18next'
   import { initReactI18next } from 'react-i18next'	import { initReactI18next } from '@intlayer/react-i18next'
   import i18next from 'i18next'	import i18next from '@intlayer/i18next'
   import { createInstance } from 'i18next'	import { createInstance } from '@intlayer/i18next'
   import { t } from 'i18next'	import { t } from '@intlayer/i18next'

   Для Next.js (next-i18next):

   Показать все данные таблицы

   Показать все данные таблицы

   Открыть таблицу в модальном окне для четкого просмотра всех данных

   Было	Стало
   import { serverSideTranslations } from 'next-i18next/serverSideTranslations'	import { serverSideTranslations } from '@intlayer/next-i18next'
   import { appWithTranslation } from 'next-i18next'	import { appWithTranslation } from '@intlayer/next-i18next'
   import { useTranslation } from 'next-i18next'	import { useTranslation } from '@intlayer/next-i18next'

2. 5

   Включение ИИ-автоматизации перевода

   Необязательно

   Когда Intlayer настроен, вы можете использовать CLI для автоматического заполнения недостающих переводов:

   bash

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   # Проверить отсутствующие переводы (добавьте в CI)npx intlayer test# Заполнить недостающие переводы с помощью ИИnpx intlayer fill

   Добавьте конфигурацию ИИ в ваш intlayer.config.ts:

   intlayer.config.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import { Locales, type IntlayerConfig } from "intlayer";
   import { syncJSON } from "@intlayer/sync-json-plugin";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         format: "i18next",
         source: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/locales",
       }),
     ],
     ai: {
       apiKey: process.env.OPENAI_API_KEY,
       // provider: "openai",     // по умолчанию
       // model: "gpt-4o-mini",   // по умолчанию
     },
   };
   
   export default config;

   Ознакомьтесь с Документацией по Intlayer CLI, чтобы изучить все доступные возможности.

Что можно удалить после миграции

После настройки адаптера совместимости следующий стандартный бойлерплейт react-i18next / i18next можно удалить:

Когда вы будете готовы двигаться дальше, Intlayer автоматически обнаружит все файлы .content.ts и .content.json в любом месте вашей кодовой базы (по умолчанию, в любом месте внутри ./src). Вы можете поместить файл my-component.content.ts прямо рядом с вашим кодом MyComponent.tsx, и Intlayer обнаружит его на этапе сборки без дополнительной настройки — не нужно никаких импортов, регистрации или центрального index-файла. Это делает совместное размещение переводов невероятно удобным.

Настройка TypeScript

Intlayer использует расширение модулей (module augmentation), чтобы предоставить полноценный IntelliSense в TypeScript для ключей перевода. Убедитесь, что ваш tsconfig.json включает автоматически сгенерированные типы:

{  // ... Ваша текущая конфигурация TypeScript  "include": [    // ... Ваша текущая конфигурация TypeScript    ".intlayer/**/*.ts", // Включает автосгенерированные типы  ],}

Настройка Git

Добавьте сгенерированную директорию Intlayer в ваш .gitignore:

# Игнорировать файлы, сгенерированные Intlayer.intlayer

Узнать больше

• Визуальный редактор — Управляйте переводами визуально прямо в браузере: Intlayer Visual Editor
• CMS — Вынесите контент за пределы кода и управляйте им удаленно: Intlayer CMS
• VS Code Расширение — Получите автодополнение и обнаружение ошибок в реальном времени: Intlayer VS Code Extension
• Справочник по CLI — Полный список команд интерфейса командной строки: Intlayer CLI
• Intlayer с React — Полное руководство по настройке в React: intlayerwithvite+react.md
• Intlayer с Next.js — Полное руководство по настройке в Next.js: intlayerwithnextjs_16.md