Перехід з next-intl на Intlayer

Чому мігрувати з next-intl на Intlayer?

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

Рекомендований підхід для існуючих додатків — це compat adapter: встановіть @intlayer/next-intl, який надає той же API, що й next-intl, але делегує всю роботу перекладу Intlayer під капотом.

Ви зберігаєте свої існуючі useTranslations, getTranslations, NextIntlClientProvider та подібне — єдина зміна — це шлях імпорту. Переструктуризація сигнатур викликів, форм реквізитів або структури компонентів не потрібна.

З часом ви можете опціонально мігрувати окремі файли до багатішого формату .content.ts Intlayer, щоб розблокувати візуальний редактор, CMS та область видимості вмісту на рівні компонентів — але цей крок повністю опціональний і може бути виконаний поступово.

Зміст

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

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

1. 1

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

   Встановіть основні пакети Intlayer та адаптер сумісності @intlayer/next-intl:

   bash

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

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

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

   npx intlayer-cli init --interactive

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

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

   bash

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

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

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

   npm install intlayer next-intlayer @intlayer/next-intl @intlayer/sync-json-plugin

   Тримайте next-intl встановленим — він все ще необхідний для маршрутизації URL (createNavigation, createMiddleware, Link, redirect, usePathname, useRouter). Адаптер сумісності не замінює шар маршрутизації.

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({
         // 'icu' відповідає синтаксису ICU заповнювачів next-intl: {name}, {count, plural, ...}
         format: "icu",
         source: ({ locale }) => `./messages/${locale}.json`,
         location: "messages",
       }),
     ],
   };
   
   export default config;

   source відображує локаль на шлях її JSON файлу. location повідомляє спостерігачу Intlayer, яку папку моніторити на предмет змін. Опція format: 'icu' гарантує, що ICU заповнювачі на кшталт {name} та {count, plural, one {# item} other {# items}} розпарсюються правильно.

   Для повного переліку параметрів конфігурації дивіться документацію конфігурації.

3. 3

   Додайте плагін Intlayer до Next.js

   Обгорніть вашу існуючу конфігурацію Next.js за допомогою createNextIntlPlugin із @intlayer/next-intl/plugin. Цей wrapper складає withIntlayer та реєструє псевдоніми next-intl → @intlayer/next-intl для вас:

   next.config.ts

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

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

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

   import type { NextConfig } from "next";
   import { createNextIntlPlugin } from "@intlayer/next-intl/plugin";
   
   const withIntlayer = createNextIntlPlugin();
   
   const nextConfig: NextConfig = {
     /* ваші існуючі параметри конфігурації */
   };
   
   export default withIntlayer(nextConfig);

   createNextIntlPlugin() обгортає withIntlayer, автоматично виявляє Webpack або Turbopack, налаштовує спостереження вмісту, компіляцію словників та — критично — впровадження псевдонімів модулів, щоб ваші існуючі виклики import … from 'next-intl' прозоро перенаправлялися на @intlayer/next-intl під час побудови. Записи маршрутизації next-intl/routing залишаються спрямованими на реальний пакет. Жодні зміни вихідних файлів не потрібні.

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

   Вам більше не потрібні getRequestConfig або loadMessages. З next-intl вам довелося писати файл src/i18n.ts, який завантажував JSON пакети повідомлень при кожному запиті через getRequestConfig. Intlayer компілює всі словники в час побудови, тому немає кроку завантаження під час виконання. Ви можете повністю видалити цей файл (або зберегти тільки частини маршрутизації, якщо ви все ще використовуєте createNavigation).

Це все для швидкої міграції. Ваш додаток тепер працює на Intlayer, зберігаючи кожний next-intl імпорт та API незмінним.

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

tsx

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

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

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

// Компонент клієнта — 'about' — це зареєстрований ключ словникаconst t = useTranslations("about");t("counter.label"); // ✓ автоматичне доповненняt("does.not.exist"); // ✗ Помилка TypeScript// Серверний компонентconst t = await getTranslations("about");t("counter.label"); // ✓ типізовано

Повна міграція

Кроки, наведені нижче, є необов'язковими і можуть виконуватися поступово. Вони розблоковують повний набір функцій Intlayer: візуальний редактор, CMS, типізовані файли вмісту, автоматизований переклад на основі AI та інше.

1. 4

   Явне перейменування імпортів (опціонально)

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

   Обгортка createNextIntlPlugin() вже обробляє створення псевдоніма next-intl → @intlayer/next-intl на рівні bundler. Якщо ви віддаєте перевагу зробити залежність явною у вихідних файлах (і використовувати звичайний плагін withIntlayer замість цього), ви можете перейменувати імпорти вручну:

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

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

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

   До	Після
   import { useTranslations } from 'next-intl'	import { useTranslations } from '@intlayer/next-intl'
   import { useLocale } from 'next-intl'	import { useLocale } from '@intlayer/next-intl'
   import { NextIntlClientProvider } from 'next-intl'	import { NextIntlClientProvider } from '@intlayer/next-intl'
   import { getTranslations } from 'next-intl/server'	import { getTranslations } from '@intlayer/next-intl/server'
   import { getLocale } from 'next-intl/server'	import { getLocale } from '@intlayer/next-intl/server'
   import { setLocale } from 'next-intl/server'	import { setLocale } from '@intlayer/next-intl/server'
   import { getMessages } from 'next-intl/server'	import { getMessages } from '@intlayer/next-intl/server'

   Завжди залишайте імпорти маршрутизації з реального next-intl — адаптер сумісності не замінює шар маршрутизації URL:

   ts

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

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

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

   // ✅ Завжди залишайте ці імпорти з реального 'next-intl'import { createNavigation } from "next-intl/routing";import { createMiddleware } from "next-intl/server";import { defineRouting } from "next-intl/routing";

   Як альтернатива, ви можете використовувати defineRouting з @intlayer/next-intl/routing, який автоматично об'єднує конфігурацію локалі з вашого intlayer.config.ts.

2. 5

   Увімкнути автоматизацію перекладу на основі AI

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

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

   bash

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

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

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

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

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

   Див. документацію Intlayer CLI для всіх доступних опцій.

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

Після встановлення @intlayer/next-intl можна видалити наступний boilerplate код next-intl:

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

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

Intlayer використовує module augmentation для забезпечення повної intellisense TypeScript для ваших ключів перекладу. Переконайтесь, що ваш 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
• Intlayer with Next.js — Повний посібник з налаштування для Next.js: intlayerwithnextjs_16.md