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

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

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

Поскольку next-i18next использует "под капотом" react-i18next и i18next, существует две дополняющие друг друга стратегии миграции на Intlayer:

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

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

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

Оглавление

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

Следующие шаги — это необходимый минимум для запуска вашего приложения Next.js (Pages Router) с Intlayer, не меняя код ни одной страницы или компонента.

1. 1

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

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

   npm install intlayer next-intlayer react-intlayer @intlayer/next-i18next @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
   npx intlayer init

   pnpm add intlayer next-intlayer react-intlayer @intlayer/next-i18next @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
   pnpm intlayer init

   yarn add intlayer next-intlayer react-intlayer @intlayer/next-i18next @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
   yarn intlayer init

   bun add intlayer next-intlayer react-intlayer @intlayer/next-i18next @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
   bun x intlayer init

   Вы можете безопасно оставить установленными пакеты next-i18next, react-i18next и i18next во время миграции, пока все алиасы не будут настроены.

2. 2

   Настройка Intlayer

   Команда intlayer init создает базовый файл конфигурации intlayer.config.ts. Обновите его, указав ваши текущие локали, и настройте плагин syncJSON на ваши файлы сообщений next-i18next (обычно расположенные в public/locales):

   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: ({ key, locale }) => `./public/locales/${locale}/${key}.json`,
         location: "public/locales",
       }),
     ],
   };
   
   export default config;

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

3. 3

   Обновление конфигурации Next.js

   Оберните ваш текущий next.config.ts (или .js) функцией createNextI18nPlugin из @intlayer/next-i18next/plugin. Эта функция-обертка применяет withIntlayer и одновременно настраивает алиасы для next-i18next / react-i18next / i18next → @intlayer/*. Таким образом, во время сборки ваши импорты вроде import { useTranslation } from 'next-i18next' будут прозрачно перенаправлены. Вносить изменения в исходный код не требуется.

   import type { NextConfig } from "next";
   import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
   // Импорт конфигурации i18n из next-i18next.config.js можно удалить
   // import { i18n } from './next-i18next.config';
   
   const withIntlayer = createNextI18nPlugin();
   
   const nextConfig: NextConfig = {
     // Intlayer обрабатывает нативную маршрутизацию i18n в Next.js "под капотом",
     // так что вам больше не нужно передавать объект i18n сюда.
   };
   
   export default withIntlayer(nextConfig);

   Файл next-i18next.config.js больше не нужен. Intlayer компилирует все словари на этапе сборки (build-time) и берет на себя бесшовное определение локали, маршрутизацию и загрузку словарей.

   Предпочитаете использовать чистый плагин withIntlayer из next-intlayer/server? При его использовании словари будут скомпилированы, но алиасы для next-i18next / react-i18next / i18next не будут добавлены — в этом случае вам придется вручную переименовать импорты в @intlayer/* (см. Шаг 4).

На этом быстрая миграция завершена. Теперь ваше приложение Next.js работает на Intlayer, при этом все ваши вызовы useTranslation, serverSideTranslations и appWithTranslation остаются без изменений.

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

// Pages Router — 'about' — зарегистрированный namespace (пространство имен) словаря
const { t } = useTranslation("about");
t("counter.label"); // ✓ автодополнение
t("does.not.exist"); // ✗ Ошибка TypeScript

// getStaticProps / getServerSideProps (экземпляр i18next)
const tAbout = i18n.getFixedT(null, "about");
tAbout("counter.label"); // ✓ строгая типизация

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

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

1. 4

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

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

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

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

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

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

   Было	Стало
   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'
   import { useTranslation } from 'react-i18next'	import { useTranslation } from '@intlayer/react-i18next'

   Это прямые замены — вам не нужно менять сигнатуры функций, передаваемые аргументы или возвращаемые типы.

2. 5

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

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

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

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

   pnpm intlayer test
   pnpm intlayer fill

   yarn intlayer test
   yarn intlayer fill

   bun x intlayer test
   bun x intlayer fill

   Добавьте конфигурацию ИИ в ваш 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: ({ key, locale }) => `./public/locales/${locale}/${key}.json`,
         location: "public/locales",
       }),
     ],
     ai: {
       apiKey: process.env.OPENAI_API_KEY,
       // provider: "openai",     // по умолчанию
       // model: "gpt-4o-mini",   // по умолчанию
     },
   };
   
   export default config;

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

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

После настройки адаптера совместимости следующий стандартный бойлерплейт next-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 с Next.js (Pages Router) — Полное руководство по настройке в Next.js: intlayerwithnextjspagerouter.md