Creation:2026-01-10Last update:2026-05-31

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

    www.youtube.com

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

    Зміст

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

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

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

    Що таке Intlayer Compiler?

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

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

    Обмеження

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

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

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

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

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

      bash
      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. Налаштування вашого проєкту

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

      intlayer.config.ts
      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:

      next.config.ts
      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. Більше того, він надає псевдоніми для оптимізації продуктивності та повноцінно працює із Серверними Компонентами.

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

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

      src/app/layout.tsx
      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:

      src/app/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>);}
      • 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.

    6. Заповнення відсутніх перекладів

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

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

      bash
      npx intlayer test         # Перевірити наявність відсутніх перекладів
      bash
      npx intlayer fill         # Заповнити відсутні переклади
      Для отримання більш детальної інформації зверніться до документації CLI

    7. Middleware для проксі-маршрутизації мов

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

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

      src/proxy.ts
      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.

    8. Зміна мови контенту

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

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

      src/components/localeSwitcher/LocaleSwitcher.tsx
      "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.

    9. Оптимізація розміру Bundle

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

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

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

      bash
      npm install @intlayer/swc --save-dev
      Примітка: Ця оптимізація доступна лише для Next.js 13 і вище.
      Примітка: Цей пакет не встановлюється за замовчуванням, оскільки SWC-плагіни все ще експериментальні в Next.js. Це може змінитися в майбутньому.

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

    10. Витягніть вміст ваших компонентів

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

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

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

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

      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;

      Запустіть екстрактор для перетворення компонентів і витягування вмісту

      bash
      npx intlayer extract

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

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

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

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

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

    Автодоповнення

    Помилка перекладу

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

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

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

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

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

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

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

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

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

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

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

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

    Йдемо далі

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

    Next.js та Page Router
    Tanstack Start