Міграція з i18next на Intlayer

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

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

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

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

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

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

Зміст

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

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

1. 1

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

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

   bash

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

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

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

   npx intlayer-cli init --interactive

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

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

   bash

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

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

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

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

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

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({
         // відповідає синтаксису заповнювачів 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

   Оновлення псевдонімів bundler (необов'язково)

   Якщо ви використовуєте bundler (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, типізовані файли контенту, переклад на базі AI та багато іншого.

1. 4

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

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

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

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

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

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

   До	Після
   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

   Увімкнути автоматизацію перекладу на базі 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 для всіх доступних опцій.

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

Після того як адаптер сумісності буде встановлений, наступний i18next шаблонний код можна видалити:

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

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

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

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

Git Configuration

Додайте згенерований Intlayer каталог до вашого .gitignore:

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

Йдіть далі

• Visual Editor — Керуйте перекладами візуально у вашому браузері: Intlayer Visual Editor
• CMS — Екстерналізуйте та керуйте контентом віддалено: Intlayer CMS
• VS Code Extension — Отримайте автозаповнення та виявлення помилок перекладу в реальному часі: Intlayer VS Code Extension
• CLI Reference — Повний список команд CLI: Intlayer CLI