Як зробити багатомовним (i18n) існуючий додаток Next.js (посібник i18n 2026)

Ознайомтеся з Шаблоном додатку на GitHub.

Зміст

Чому інтернаціоналізація існуючого додатку є складною?

Якщо ви коли-небудь намагалися додати кілька мов до програми, яка була створена лише для однієї, ви знаєте про всі труднощі. Це не просто "важко" - це виснажливо. Вам доводиться переглядати кожен файл, знаходити кожен рядок тексту та переміщувати їх у спеціальні файли словників (dictionaries).

Потім настає найризикованіша частина: заміна всього цього тексту на хуки коду без пошкодження макета чи логіки. Це робота, яка призупиняє розробку нових функцій на тижні й здається нескінченним рефакторингом.

Що таке Intlayer Compiler?

Intlayer Compiler (Компілятор Intlayer) був створений, щоб обійти цю ручну роботу. Замість того, щоб змушувати вас вручну витягувати рядки, компілятор робить це за вас. Він сканує ваш код, знаходить текст та використовує ШІ, щоб генерувати словники у фоновому режимі. Потім він змінює ваш вихідний код під час етапу збірки, щоб впровадити необхідні i18n хуки. По суті, ви продовжуєте писати свій додаток, ніби пишете однією мовою, а компілятор автоматично обробляє багатомовне перетворення на рівні ядра.

Документація компілятора: /uk/doc/compiler

Обмеження

Оскільки компілятор виконує аналіз коду і його трансформацію (впровадження хуків та генерування словників) під час часу збірки, він може уповільнити час збірки вашого додатку.

Щоб обмежити цей вплив під час активної розробки (dev mode), ви можете налаштувати компілятор на роботу у режимі 'build-only' або відключити його, коли в ньому немає потреби.

Покрокова інструкція з налаштування Intlayer в додатку Next.js

Крок 1: Встановлення залежностей

Встановіть необхідні пакети за допомогою бажаного менеджера пакетів:

npm install intlayer next-intlayernpm install @intlayer/babel --save-devnpx intlayer init

• intlayer

  Основний пакет, що забезпечує інструменти інтернаціоналізації для управління конфігурацією, перекладом, декларацією контенту, транспіляцією та CLI командами.

• next-intlayer

  Пакет, що інтегрує Intlayer з Next.js. Він надає контекст-провайдери та хуки для інтернаціоналізації Next.js. Крім того, він включає плагін Next.js для інтеграції Intlayer з Webpack або Turbopack, а також прошарок (middleware) для виявлення бажаної мови користувача, управління файлами cookie та обробки перенаправлення URL.

Крок 2: Налаштування вашого проєкту

Створіть конфігураційний файл, щоб визначити мови вашого додатку:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.UKRAINIAN],    defaultLocale: Locales.UKRAINIAN,  },  routing: {    mode: "search-params",  },  compiler: {    /**     * Вказує, чи має бути увімкнено компілятор.     */    enabled: true,    /**     * Вихідний каталог для оптимізованих словників.     */    output: ({ locale, key }) => `compiler/${locale}/${key}.json`,    /**     * Вставте лише вміст у згенерований файл, без ключа.     */    noMetadata: false,    /**     * Префікс ключа словника     */    dictionaryKeyPrefix: "", // Remove base prefix    /**     * Вказує, чи мають компоненти зберігатися після трансформації.     * Таким чином компілятор можна запустити лише один раз для трансформації додатка, а потім видалити.     */    saveComponents: false,  },  ai: {    provider: "openai",    model: "gpt-5-mini",    apiKey: process.env.OPEN_AI_API_KEY,    applicationContext: "Це приклад простого додатку карти",  },};export default config;

Примітка: Переконайтеся, що ви встановили OPEN_AI_API_KEY у ваших змінних середовища.

За допомогою цього конфігураційного файлу ви можете налаштувати локалізовані URL-адреси, проксі-перенаправлення, мапінг файлів cookie, розташування та розширення ваших декларацій контенту, вимкнути логи Intlayer в консолі та багато іншого. Для ознайомлення з повним списком доступних параметрів, перегляньте документацію до конфігурацій.

Крок 3: Інтегруйте Intlayer до вашої конфігурації Next.js

Налаштуйте ваш Next.js для використання Intlayer:

import type { NextConfig } from "next";import { withIntlayer } from "next-intlayer/server";const nextConfig: NextConfig = {  /* Тут можуть бути ваші інші налаштування Next.js */};export default withIntlayer(nextConfig);

Плагін Next.js withIntlayer() використовується для інтеграції Intlayer із Next.js. Він забезпечує побудову файлів словників і слідкує за ними у режимі dev. Він визначає змінні середовища Intlayer у середовищах Webpack або Turbopack. Більше того, він надає псевдоніми для оптимізації продуктивності та повноцінно працює із Серверними Компонентами.

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

Компілятор Intlayer вимагає Babel для витягування та оптимізації вашого контенту. Оновіть ваш babel.config.js (або babel.config.json), щоб додати плагіни Intlayer:

const {  intlayerExtractBabelPlugin,  intlayerOptimizeBabelPlugin,  getExtractPluginOptions,  getOptimizePluginOptions,} = require("@intlayer/babel");module.exports = {  presets: ["next/babel"],  plugins: [    [intlayerExtractBabelPlugin, getExtractPluginOptions()],    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],  ],};

Крок 4: Виявлення мови на ваших сторінках

Очистіть контент RootLayout та замініть його прикладом нижче:

import type { Metadata } from "next";import type { ReactNode } from "react";import "./globals.css";import { IntlayerClientProvider, LocalPromiseParams } from "next-intlayer";import { getHTMLTextDir, getIntlayer } from "intlayer";import { getLocale } from "next-intlayer/server";export { generateStaticParams } from "next-intlayer";export const generateMetadata = async (): Promise<Metadata> => {  const locale = await getLocale();  const { title, description, keywords } = getIntlayer("metadata", locale);  return {    title,    description,    keywords,  };};const RootLayout = async ({  children,}: Readonly<{  children: ReactNode;}>) => {  const locale = await getLocale();  return (    <html lang={locale} dir={getHTMLTextDir(locale)}>      <IntlayerClientProvider defaultLocale={locale}>        <body>{children}</body>      </IntlayerClientProvider>    </html>  );};export default RootLayout;

Крок 5: Декларування вашого контенту (Автоматично)

З увімкненим компілятором вам більше не потрібно декларувати словники контенту вручну (наприклад, файли .content.ts).

Натомість, ви просто пишете ваш контент як захардкоджені рядки у вашому коді. Intlayer просканує вихідний код, згенерує переклади за допомогою налаштованого ШІ-провайдера і автоматично замінить ці рядки на локалізований контент під час етапу компіляції збірки. Все це повністю автоматизовано.

Просто пишіть ваші компоненти з захардкодженими рядками у вашій мові за замовчуванням і дозвольте Intlayer Compiler зробити все інше.

Приклад того, як виглядатиме ваша page.tsx:

import type { FC } from "react";import { IntlayerServerProvider } from "next-intlayer/server";import { getLocale } from "next-intlayer/server";const PageContent: FC = () => {return (  <>    <p>Почніть з редагування цього!</p>    <code>src/app/page.tsx</code>  </>);};export default async function Page() {const locale = await getLocale();return (  <IntlayerServerProvider locale={locale}>    <PageContent />  </IntlayerServerProvider>);}

{key: "page-content",content: {  nodeType: "translation",  translation: {    en: {      getStartedByEditingThis: "Get started by editing this!",    },    fr: {      getStartedByEditingThis: "Commencez par éditer ceci !",    },    uk: {      getStartedByEditingThis: "Почніть з редагування цього!",    },  }}}

import { type FC } from "react";import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";import { getLocale } from "next-intlayer/server";const PageContent: FC = () => {const content = useIntlayer("page-content");return (  <>    <p>{content.getStartedByEditingThis}</p>    <code>src/app/page.tsx</code>  </>);};export default async function Page() {const locale = await getLocale();return (  <IntlayerServerProvider locale={locale}>    <PageContent />  </IntlayerServerProvider>);}

• IntlayerClientProvider використовується для розповсюдження мови до клієнтських компонентів-нащадків.

• Водночас IntlayerServerProvider використовується для забезпечення мови серверним компонентам-нащадкам.

  Layout and page cannot share a common server context because the server context system is based on a per-request data store (via React's cache mechanism), causing each "context" to be re-created for different segments of the application. Placing the provider in a shared layout would break this isolation, preventing the correct propagation of the server context values to your server components.

(Опціонально) Крок 7: Заповнення відсутніх перекладів

Intlayer надає CLI-інструмент, щоб допомогти вам заповнити відсутні переклади. Ви можете використовувати команду intlayer для перевірки та заповнення відсутніх перекладів із вашого коду.

npx intlayer test         # Перевірити наявність відсутніх перекладів

npx intlayer fill         # Заповнити відсутні переклади

Для отримання більш детальної інформації зверніться до документації CLI

(Необов'язково) Крок 8: Middleware для проксі-маршрутизації мов

Якщо ви хочете автоматично перенаправляти користувачів на їхню улюблену мову, налаштуйте проксі middleware:

export { intlayerProxy as proxy } from "next-intlayer/proxy";export const config = {  matcher:    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",};

intlayerProxy використовується для виявлення обраної мови користувача та його перенаправлення на відповідну URL-адресу, як це визначено у файлі конфігурації. Крім того, це дозволяє зберігати бажану мову користувача у cookie.

(Необов'язково) Крок 9: Зміна мови контенту

Найбільш рекомендований спосіб зміни мови контенту в Next.js, використання компонента Link для направлення користувача на маршрут з відповідною мовою. Це використовує функцію prefetch фреймворку Next.js і дозволяє уникнути жорсткого перезавантаження сторінки.

"use client";import type { FC } from "react";import { Locales, getHTMLTextDir, getLocaleName } from "intlayer";import { useLocale } from "next-intlayer";export const LocaleSwitcher: FC = () => {  const { locale, availableLocales, setLocale } = useLocale();  return (    <div>      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>      <div id="localePopover" popover="auto">        {availableLocales.map((localeItem) => (          <button            key={localeItem}            aria-current={locale === localeItem ? "page" : undefined}            onClick={() => setLocale(localeItem)}          >            <span>              {/* Мова - наприклад: UK */}              {localeItem}            </span>            <span>              {/* Назва мови її власною мовою - наприклад: Українська */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* Назва мови поточною обраною мовою - наприклад: Francés (якщо обрана іспанська) */}              {getLocaleName(localeItem)}            </span>            <span dir="ltr" lang={Locales.ENGLISH}>              {/* Назва мови англійською - наприклад: Ukrainian */}              {getLocaleName(localeItem, Locales.ENGLISH)}            </span>          </button>        ))}      </div>    </div>  );};

Альтернативним варіантом є використання функції setLocale, яка надається хуком useLocale. Ця функція не підтримує prefetch сторінок. Більше деталей дивіться у документації до хука useLocale.

(Необов'язково) Крок 10: Оптимізація розміру Bundle

При використанні next-intlayer, словники за замовчуванням включаються в bundle для кожної сторінки. Для оптимізації розміру bundle Intlayer надає опціональний SWC-плагін, який інтелектуально замінює виклики useIntlayer за допомогою макросів. Це гарантує, що словники включаються лише в bundle тих сторінок, які їх дійсно використовують.

Щоб увімкнути цю оптимізацію, встановіть пакет @intlayer/swc. Після встановлення next-intlayer автоматично виявить і використовуватиме плагін:

npm install @intlayer/swc --save-dev

Примітка: Ця оптимізація доступна лише для Next.js 13 і вище.

Примітка: Цей пакет не встановлюється за замовчуванням, оскільки SWC-плагіни все ще експериментальні в Next.js. Це може змінитися в майбутньому.

Примітка: Якщо ви встановили опцію (у конфігурації словника) importMode: 'dynamic' або importMode: 'fetch', вона залежатиме від Suspense, тому вам потрібно буде обгорнути виклики useIntlayer у межу Suspense. Це означає, що ви не зможете використовувати useIntlayer безпосередньо на верхньому рівні ваших компонентів Сторінки / Layout.

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

Intlayer використовує розширення модулів (module augmentation), щоб скористатися перевагами TypeScript і зробити вашу базу коду міцнішою.

Переконайтеся, що конфігурація TypeScript включає автоматично згенеровані типи.

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

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

Рекомендовано ігнорувати файли, згенеровані Intlayer. Це дозволяє уникнути їх завантаження до вашого Git-репозиторію.

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

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

Розширення VS Code

Для покращення досвіду розробки з Intlayer ви можете встановити офіційне розширення Intlayer для VS Code.

Встановити з VS Code Marketplace

Це розширення забезпечує:

• Автодоповнення для ключів перекладу.
• Виявлення помилок у реальному часі для відсутніх перекладів.
• Вбудований попередній перегляд перекладеного контенту.
• Швидкі дії (Quick actions) для легкого створення та оновлення перекладів.

Прочитайте документацію до розширення VS Code Intlayer для отримання детальних інструкцій щодо використання розширення.

(Необов'язково) Крок 1 : Витягніть вміст ваших компонентів

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

Щоб спростити цей процес, Intlayer пропонує компілятор / екстрактор для перетворення ваших компонентів і витягування вмісту.

Щоб налаштувати його, ви можете додати розділ compiler у свій файл intlayer.config.ts:

import { type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... Інша частина вашої конфігурації
  compiler: {
    /**
     * Вказує, чи повинен бути включений компілятор.
     */
    enabled: true,

    /**
     * Визначає шлях до вихідних файлів
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * Вказує, чи повинні компоненти зберігатися після перетворення. Таким чином, компілятор можна запустити лише один раз для перетворення програми, а потім видалити.
     */
    saveComponents: false,

    /**
     * Префікс ключа словника
     */
    dictionaryKeyPrefix: "",
  },
};

export default config;

npx intlayer extract

npm install @intlayer/babel --save-dev

const { intlayerExtractBabelPlugin, getExtractPluginOptions,} = require("@intlayer/babel");module.exports = { presets: ["next/babel"], plugins: [   // Витягування вмісту з компонентів у словники   [intlayerExtractBabelPlugin, getExtractPluginOptions()], ],};

npm run build # Або npm run dev

Йдемо далі

Для подальшого розвитку ви можете впровадити візуальний редактор або винести ваш контент назовні за допомогою CMS.