Как сделать многоязычным (i18n) существующее приложение Next.js (руководство i18n 2026)

См. Шаблон приложения на GitHub.

Оглавление

Почему сложно интернационализировать существующее приложение?

Если вы когда-либо пытались добавить несколько языков в приложение, которое было создано только для одного, вы знаете, как это сложно. Это не просто «сложно», это утомительно. Вам приходится просматривать каждый файл, находить каждую текстовую строку и переносить их в отдельные файлы словарей.

Затем наступает рискованная часть: замена всего этого текста программными хуками без нарушения верстки или логики. Это работа, которая останавливает разработку новых функций на недели и ощущается как бесконечный рефакторинг.

Что такое компилятор Intlayer?

Компилятор Intlayer был создан, чтобы избавить вас от этой рутины. Вместо того чтобы вручную извлекать строки, компилятор делает это за вас. Он сканирует ваш код, находит текст и использует ИИ для генерации словарей в фоновом режиме. Затем он изменяет ваш код во время сборки, чтобы добавить необходимые i18n-хуки. По сути, вы продолжаете писать приложение так, как будто оно на одном языке, а компилятор автоматически обрабатывает многоязычное преобразование.

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

Ограничения

Поскольку компилятор выполняет анализ и преобразование кода (вставку хуков и генерацию словарей) на этапе компиляции, он может замедлить процесс сборки вашего приложения.

Чтобы смягчить это влияние во время разработки, вы можете настроить компилятор для работы в режиме 'build-only' или полностью отключить его, если он не нужен.

Пошаговое руководство по настройке Intlayer в приложении Next.js

Шаг 1: Установка зависимостей

Установите необходимые пакеты с помощью npm:

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, а также прокси для определения предпочтительного языка пользователя, управления файлами cookie и обработки перенаправлений URL.

Шаг 2: Настройка проекта

Создайте файл конфигурации для настройки языков вашего приложения:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.RUSSIAN],    defaultLocale: Locales.RUSSIAN,  },  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-адреса, перенаправление прокси, названия куки, расположение и расширение ваших объявлений контента, отключить логи Intlayer в консоли и многое другое. Полный список доступных параметров см. в документации по конфигурации.

Шаг 3: Интеграция Intlayer в конфигурацию Next.js

Настройте параметры Next.js для использования Intlayer:

import type { NextConfig } from "next";import { withIntlayer } from "next-intlayer/server";const nextConfig: NextConfig = {  /* параметры конфигурации здесь */};export default withIntlayer(nextConfig);

Плагин Next.js withIntlayer() используется для интеграции Intlayer с Next.js. Он обеспечивает сборку файлов объявления контента и отслеживает их изменения в режиме разработки. Он определяет переменные среды Intlayer в средах Webpack или Turbopack. Кроме того, он предоставляет алиасы для оптимизации производительности и обеспечивает совместимость с серверными компонентами.

Шаг 4: Настройка 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()],  ],};

Шаг 5: Определение языка на ваших страницах

Удалите все содержимое из 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;

Шаг 6: Компиляция компонентов

При включенном компиляторе вам больше не нужно вручную объявлять словари контента (такие как файлы .content.ts).

Вместо этого вы можете писать свой контент прямо в коде в виде строк. Intlayer проанализирует ваш код, сгенерирует переводы с помощью настроенного ИИ-провайдера и заменит строки локализованным контентом во время сборки.

Просто пишите свои компоненты с захардкоженными строками на вашем языке по умолчанию. Компилятор позаботится об остальном.

Пример того, как может выглядеть ваша страница:

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: {      getStartedByEditing: "Get started by editing",    },    fr: {      getStartedByEditing: "Commencez par éditer",    },    ru: {      getStartedByEditing: "Начните с редактирования",    },  }}}

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.getStartedByEditing}</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: Настройка прокси для определения языка

Настройте прокси для определения предпочтительного языка пользователя:

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

intlayerProxy используется для определения предпочтительного языка пользователя и перенаправления его на соответствующий URL, как указано в конфигурации. Кроме того, он позволяет сохранять предпочтительный язык пользователя в куки.

(Необязательно) Шаг 8: Изменение языка контента

Для изменения языка контента в Next.js рекомендуется использовать компонент Link для перенаправления пользователей на соответствующую локализованную страницу. Компонент Link обеспечивает предзагрузку страницы, что помогает избежать полной перезагрузки.

"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>              {/* Язык - напр. RU */}              {localeItem}            </span>            <span>              {/* Язык на своем языке - напр. Русский */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* Язык на текущем языке - напр. Французский, когда текущий язык Locales.RUSSIAN */}              {getLocaleName(localeItem)}            </span>            <span dir="ltr" lang={Locales.ENGLISH}>              {/* Язык на английском - напр. Russian */}              {getLocaleName(localeItem, Locales.ENGLISH)}            </span>          </button>        ))}      </div>    </div>  );};

Альтернативный способ, использовать функцию setLocale, предоставляемую хуком useLocale. Эта функция не позволит предзагружать страницу. См. документацию хука useLocale для получения подробной информации.

(Необязательно) Шаг 10: Оптимизация размера бандла

При использовании next-intlayer словари по умолчанию включаются в бандл для каждой страницы. Для оптимизации размера бандла Intlayer предоставляет дополнительный плагин SWC, который интеллектуально заменяет вызовы useIntlayer макросами. Это гарантирует, что словари включаются только в те бандлы страниц, которые их действительно используют.

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

npm install @intlayer/swc --save-dev

Примечание: Эта оптимизация доступна только для Next.js 13 и выше.

Примечание: Этот пакет не устанавливается по умолчанию, так как плагины SWC в Next.js все еще являются экспериментальными. Это может измениться в будущем.

Примечание: Если вы установите параметр importMode: 'dynamic' или importMode: 'fetch' (в конфигурации dictionary), он будет полагаться на Suspense, поэтому вам придется обернуть вызовы useIntlayer в границу Suspense. Это означает, что вы не сможете использовать useIntlayer непосредственно на верхнем уровне вашего компонента Страницы / Лейаута.

Настройка 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

Это расширение предоставляет:

• Автодополнение для ключей перевода.
• Обнаружение ошибок в реальном времени для отсутствующих переводов.
• Инлайновое превью переведенного контента.
• Быстрые действия для легкого создания и обновления переводов.

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

(Опционально) Шаг 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.