Миграция с i18next на Intlayer

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

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

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

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

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

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

Оглавление

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

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

1. 1

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

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

   bash

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

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

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

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

   Вы можете смело оставить установленным i18next — адаптер совместимости использует его как devDependency / peerDependency для типов TypeScript.

2. 2

   Настройка Intlayer

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

   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({
         // соответствует синтаксису плейсхолдеров 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

   Обновление алиасов сборщика (опционально)

   Если вы используете сборщик (Vite, Webpack, esbuild), вы можете внедрить алиас модуля, чтобы import ... from 'i18next' автоматически разрешался в @intlayer/i18next. Это избавит от необходимости изменять пути импорта вручную по всей кодовой базе.

   Для Vite:

   vite.config.ts

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

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

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

   import { defineConfig } from "vite";
   import i18nextVitePlugin from "@intlayer/i18next/plugin";
   
   export default defineConfig({
     plugins: [i18nextVitePlugin()],
   });

   i18nextVitePlugin() оборачивает плагин intlayer() из vite-intlayer и автоматически добавляет алиас i18next → @intlayer/i18next. Использование обычного плагина intlayer() из vite-intlayer скомпилирует словари, но не добавит алиас — в таком случае вам придется вручную переименовывать импорты в @intlayer/i18next (см. следующий шаг).

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

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

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

1. 4

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

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

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

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

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

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

   Было	Стало
   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'

   Это прямая замена — никаких изменений в сигнатурах вызовов, аргументах или возвращаемых типах не требуется.

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, чтобы изучить все доступные возможности.

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

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

Когда вы будете готовы двигаться дальше, Intlayer автоматически обнаружит все файлы .content.ts и .content.json в любом месте вашей кодовой базы (по умолчанию, в любом месте внутри ./src). Вы можете поместить файл my-component.content.ts прямо рядом с вашим кодом, и 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