Перехід від 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 Pages без змін — єдиною змінею є ініціалізація.

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

Цей посібник спочатку охоплює Стратегію 1 (адаптер типу "plug-and-play"), а потім проводить вас через опціональну повну міграцію.

Зміст

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

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

1. 1

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

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

   bash

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

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

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

   npx intlayer-cli init --interactive

   прапор --interactive опціональний. Використовуйте intlayer-cli init, якщо ви AI агент.

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

   bash

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

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

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

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

   Ви можете безпечно зберігати next-i18next, react-i18next та i18next встановленими під час міграції, хоча ви видалите їх після встановлення псевдонімів.

2. 2

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

   Команда intlayer init створює стартовий файл intlayer.config.ts. Оновіть його відповідно до ваших існуючих локалей та вкажіть плагіну syncJSON на ваші файли повідомлень next-i18next (зазвичай всередині public/locales):

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

   source відображає локаль та простір назв (key) на шлях до його JSON файлу. location повідомляє спостерігачу 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' прозоро перенаправляються під час компіляції. Жодних змін вихідного кода не потрібно.

   next.config.ts

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

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

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

   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 керує маршрутизацією Next.js i18n під капотом,
     // тому вам більше не потрібно передавати об'єкт i18n сюди.
   };
   
   export default withIntlayer(nextConfig);

   Вам більше не потрібен файл next-i18next.config.js. Intlayer компілює всі словники під час компіляції, беручи на себе визначення локалі, маршрутизацію та завантаження словника без втручання.

   Надаєте перевагу простому withIntlayer з next-intlayer/server? Він компілює ваші словники, але не додає псевдоніми next-i18next / react-i18next / i18next — тоді вам потрібно буде вручну перейменувати імпорти на @intlayer/* (див. крок 4).

Ось і все для швидкої міграції. Ваш додаток Next.js тепер працює на Intlayer, зберігаючи цілісність всіх викликів useTranslation, serverSideTranslations та appWithTranslation.

Типізовані ключі перекладу — автоматично. Після того як Intlayer скомпілює ваші словники, useTranslation та getFixedT типізуються щодо вашого фактичного вмісту. Ключі автозавершуються у вашій IDE, а невалідні шляхи викликають помилки TypeScript під час компіляції — додаткове налаштування не потрібно.

tsx

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

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

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

// Pages Router — 'about' це зареєстрований ключ словника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, типізовані файли вмісту, AI-потужний переклад та інше.

1. 4

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

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

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

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

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

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

   Раніше	Тепер
   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

   Включення автоматизації перекладу на основі 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: ({ 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 для всіх доступних опцій.

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

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

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

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

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

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

Git Configuration

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

# Ignore the files generated by Intlayer.intlayer

Йдіть далі

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