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

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

    www.youtube.com

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

    Оглавление

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

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

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

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

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

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

    Ограничения

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

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

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

    1. Установка зависимостей

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

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

    2. Настройка проекта

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

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

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

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

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

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

    6. Компиляция компонентов

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

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

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

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

      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.

    7. Заполнение недостающих переводов

      Необязательно

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

      bash
      npx intlayer test         # Проверить наличие недостающих переводов
      bash
      npx intlayer fill         # Заполнить недостающие переводы
      Для получения более подробной информации обратитесь к документации CLI

    8. Настройка прокси для определения языка

      Необязательно

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

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

    9. Изменение языка контента

      Необязательно

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

      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>              {/* Язык - напр. 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 автоматически обнаружит и использует плагин:

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

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

    11. Извлечение содержимого ваших компонентов

      Необязательно

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

      Чтобы упростить этот процесс, 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

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

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

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

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

    Идите дальше

    Чтобы пойти еще дальше, вы можете внедрить визуальный редактор или вынести свой контент во внешнюю среду с помощью CMS.

    Next.js и Page Router
    Tanstack Start