Міграція з react-i18next / i18next на Intlayer

Чому варто перейти з react-i18next / i18next на Intlayer?

Стратегії міграції

Існують дві взаємодоповнюючі стратегії для переходу з react-i18next / i18next на Intlayer:

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

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

Цей посібник спочатку охоплює Стратегію 1 (drop-in compat adapter), а потім розглядає необов'язкову повну міграцію.

Зміст

Швидка міграція

Наступні кроки — мінімум необхідний для запуску вашої існуючої програми react-i18next на Intlayer без змін коду.

1. 1

   Встановлення залежностей

   Встановіть основні пакети Intlayer та адаптери сумісності:

   bash

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   npx intlayer-cli init --interactive

   флаг --interactive необов'язковий. Використовуйте intlayer-cli init, якщо ви AI-агент.

   Ця команда визначить ваше середовище та встановить необхідні пакети. Наприклад:

   bash

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   npm install intlayer react-intlayer @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin

   Ви можете залишити встановленими react-i18next та i18next — адаптери сумісності використовують їх як devDependencies / необов'язкові peerDependencies для типів TypeScript. Вам не потрібно змінювати жодних однорівневих залежностей 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 повідомляє спостерігачу Intlayer, яку папку моніторити на предмет змін. Параметр format: 'i18next' гарантує, що заповнювачі на кшталт {{name}} аналізуються правильно.

3. 3

   Додавання плагіна Intlayer до вашого Bundler

   Обгорніть вашу існуючу конфігурацію bundler за допомогою плагіна сумісності. Він компонує основний плагін 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 компілює всі словники під час побудови, тому немає кроку завантаження під час виконання. Провайдер з псевдонімом обробляє ініціалізацію за вас.

Це все для швидкої міграції. Ваша програма тепер працює на 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, типізовані файли вмісту, переклад з використанням AI та інше.

1. 4

   Явне перейменування імпорту (необов'язково)

   Необов'язково

   Плагіни Intlayer вже обробляють aliasing на рівні bundler. Якщо ви віддаєте перевагу явній вказівці залежності у своїх файлах, ви можете перейменувати імпорти вручну:

   Показати весь вміст таблиці

   Показати весь вміст таблиці

   Відкрийте таблицю в модальному вікні, щоб чітко переглянути всі дані

   Раніше	Після
   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

   Увімкнення автоматизованого перекладу з AI

   Необов'язково

   Коли Intlayer буде підключено, використовуйте його CLI для автоматичного заповнення відсутніх перекладів:

   bash

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   # Тест на відсутні переклади (додайте в CI)npx intlayer test# Заповнити відсутні переклади за допомогою AInpx intlayer fill

   Додайте конфігурацію AI до 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 для всіх доступних опцій.

Що можна видалити після міграції

Після того як адаптери сумісності будуть на місці, наступний boilerplate react-i18next / i18next можна видалити:

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

Налаштування TypeScript

Intlayer використовує модульне розширення для забезпечення повної TypeScript intellisense для ваших ключів перекладу. Переконайтесь, що ваш tsconfig.json включає автоматично генеровані типи:

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

Конфігурація Git

Додайте сформовану директорію Intlayer до вашого .gitignore:

# Ігнорувати файли, генеровані Intlayer.intlayer

Йди далі

• Visual Editor — Керуйте перекладами візуально у вашому браузері: Intlayer Visual Editor
• CMS — Екстерналізуйте та керуйте контентом віддалено: Intlayer CMS
• VS Code Extension — Отримуйте автозаповнення та виявлення помилок перекладу в реальному часі: Intlayer VS Code Extension
• CLI Reference — Повний список команд CLI: Intlayer CLI
• Intlayer with React — Повний посібник налаштування для React: intlayerwithvite+react.md
• Intlayer with Next.js — Повний посібник налаштування для Next.js: intlayerwithnextjs_16.md