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

ВидеоКод

www.youtube.com

Open embedded page in fullscreen

ide.intlayer.org

Open embedded page in fullscreen

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

Оглавление

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

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

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

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

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

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

Ограничения

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

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

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

1. 1

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

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

   bash

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   npx intlayer init --interactive
   

   флаг --interactive не является обязательным. Используйте intlayer-cli init, если вы являетесь ИИ-агентом.

   Эта команда определит вашу среду и установит необходимые пакеты. Например:

   bash

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   npm install intlayer next-intlayer
   npm install @intlayer/babel --save-dev
   

   • intlayer

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

   • next-intlayer

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

2. 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. 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. 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. 5

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

   Удалите все содержимое из RootLayout и замените его следующим кодом:

   src/app/layout.tsx

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import type { Metadata } from "next";
   import type { ReactNode } from "react";
   import "./globals.css";
   import { IntlayerProvider, 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)}>
         <body>
           <IntlayerProvider defaultLocale={locale}>{children}</IntlayerProvider>
         </body>
       </html>
     );
   };
   
   export default RootLayout;
   

6. 6

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

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

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

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

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

   CodeOutput

   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>
     );
   }
   
7. 7

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

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

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

   bash

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   npx intlayer test         # Проверить наличие недостающих переводов
   

   bash

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   npx intlayer fill         # Заполнить недостающие переводы
   

   Для получения более подробной информации обратитесь к документации CLI

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

   Начиная с Intlayer v9, этот middleware соблюдает опцию routing.enableProxy (true по умолчанию). Установите routing.enableProxy: false в вашей конфигурации, чтобы превратить его в pass-through без удаления этого файла. См. примечания к выпуску v9.

9. 8

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

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

   Для изменения языка контента в 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. 10

    Оптимизация размера бандла

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

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

    Плагин @intlayer/babel уже интегрирует оптимизацию бандлинга (см. babel.config.js). Но плагин @intlayer/swc более производителен. Если вы удалите плагин @intlayer/babel, вы можете использовать плагин @intlayer/swc.

    Чтобы включить эту оптимизацию, установите пакет @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 непосредственно на верхнем уровне вашего компонента Страницы / Лейаута.

</Step>

11. 1

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

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

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

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

    Команда извлеченияКомпилятор Babel

    Запустите экстрактор для преобразования компонентов и извлечения содержимого

    bash

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

    npx intlayer extract
    

    Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

    bash

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

    npm install @intlayer/babel --save-dev
    

    babel.config.js

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

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

    bash

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

    npm run build # Или npm run dev
    

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

Идите дальше

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