---
createdAt: 2025-08-23
updatedAt: 2025-10-29
title: Intlayer и next-i18next
description: Интеграция Intlayer с next-i18next для комплексного решения интернационализации Next.js
keywords:
  - i18next
  - next-i18next
  - Intlayer
  - Интернационализация
  - Блог
  - Next.js
  - JavaScript
  - React
slugs:
  - blog
  - intlayer-with-next-i18next
history:
  - version: 7.0.6
    date: 2025-11-01
    changes: Добавлен плагин loadJSON
  - version: 7.0.0
    date: 2025-10-29
    changes: Переход на плагин syncJSON и полный переписанный код
---

# Интернационализация Next.js (i18n) с next-i18next и Intlayer

## Содержание

<TOC/>

## Что такое next-i18next?

**next-i18next** — это один из самых популярных фреймворков для интернационализации (i18n) в приложениях Next.js. Построенный на мощной экосистеме **i18next**, он предоставляет комплексное решение для управления переводами, локализацией и переключением языков в проектах Next.js.

Однако next-i18next имеет некоторые сложности:

- **Сложная конфигурация**: Настройка next-i18next требует нескольких конфигурационных файлов и тщательной настройки экземпляров i18n на стороне сервера и клиента.
- **Разрозненные переводы**: Файлы переводов обычно хранятся в отдельных директориях от компонентов, что затрудняет поддержание согласованности.
- **Ручное управление пространствами имён**: Разработчикам необходимо вручную управлять пространствами имён и обеспечивать правильную загрузку ресурсов переводов.
- **Ограниченная типобезопасность**: Поддержка TypeScript требует дополнительной настройки и не обеспечивает автоматическую генерацию типов для переводов.

## Что такое Intlayer?

**Intlayer** — это инновационная, открытая библиотека интернационализации, разработанная для устранения недостатков традиционных решений i18n. Она предлагает современный подход к управлению контентом в приложениях Next.js.

Смотрите конкретное сравнение с next-intl в нашем блоге [next-i18next vs. next-intl vs. Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ru/next-i18next_vs_next-intl_vs_intlayer.md).

## Почему стоит сочетать Intlayer с next-i18next?

Хотя Intlayer предоставляет отличное автономное решение для i18n (см. наше [руководство по интеграции с Next.js](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_with_nextjs_16.md)), вы можете захотеть комбинировать его с next-i18next по нескольким причинам:

1. **Существующая кодовая база**: У вас уже есть реализованная система next-i18next, и вы хотите постепенно перейти на улучшенный опыт разработки с Intlayer.
2. **Требования наследия**: Ваш проект требует совместимости с существующими плагинами или рабочими процессами i18next.
3. **Знакомство команды**: Ваша команда привыкла к next-i18next, но хочет лучшее управление контентом.

**Для этого Intlayer может быть реализован как адаптер для next-i18next, чтобы помочь автоматизировать ваши JSON-переводы в CLI или CI/CD пайплайнах, тестировать ваши переводы и многое другое.**

В этом руководстве показано, как использовать превосходную систему декларации контента Intlayer, сохраняя при этом совместимость с next-i18next.

---

## Пошаговое руководство по настройке Intlayer с next-i18next

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

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

```bash packageManager="npm"
npm install intlayer @intlayer/sync-json-plugin
```

```bash packageManager="pnpm"
pnpm add intlayer @intlayer/sync-json-plugin
```

```bash packageManager="yarn"
yarn add intlayer @intlayer/sync-json-plugin
```

```bash packageManager="bun"
bun add intlayer @intlayer/sync-json-plugin
```

**Объяснение пакетов:**

- **intlayer**: Основная библиотека для декларации и управления контентом
- **@intlayer/sync-json-plugin**: Плагин для синхронизации деклараций контента Intlayer с форматом JSON i18next

### Шаг 2: Реализация плагина Intlayer для обёртывания JSON

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

**Если вы также хотите экспортировать JSON-словарь для i18next**, добавьте плагин `syncJSON`:

```typescript fileName="intlayer.config.ts"
import { Locales, type IntlayerConfig } from "intlayer";
import { syncJSON } from "@intlayer/sync-json-plugin";

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    defaultLocale: Locales.ENGLISH,
  },
  plugins: [
    syncJSON({
      source: ({ key, locale }) => `./public/locales/${locale}/${key}.json`,
    }),
  ],
};

export default config;
```

Плагин `syncJSON` автоматически обернет JSON. Он будет читать и записывать JSON-файлы без изменения архитектуры контента.

Если вы хотите, чтобы JSON сосуществовал с файлами декларации контента Intlayer (`.content` файлы), Intlayer будет работать следующим образом:

    1. загрузит как JSON, так и файлы декларации контента и преобразует их в словарь Intlayer.
    2. если возникнут конфликты между JSON и файлами декларации контента, Intlayer выполнит слияние всех словарей. В зависимости от приоритета плагинов и файлов декларации контента (все настраивается).

Если изменения внесены с помощью CLI для перевода JSON или с использованием CMS, Intlayer обновит JSON-файл с новыми переводами.

Для получения дополнительной информации о плагине `syncJSON` обратитесь к [документации плагина syncJSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/plugins/sync-json.md).

---

### (Необязательно) Шаг 3: Реализация перевода JSON по компонентам

По умолчанию Intlayer загрузит, объединит и синхронизирует как JSON, так и файлы декларации контента. Подробнее смотрите в [документации по декларации контента](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/dictionary/content_file.md). Но если вы предпочитаете, используя плагин Intlayer, вы также можете реализовать управление локализованным JSON по компонентам в любом месте вашей кодовой базы.

Для этого вы можете использовать плагин `loadJSON`.

```ts fileName="intlayer.config.ts"
import { Locales, type IntlayerConfig } from "intlayer";
import { loadJSON, syncJSON } from "@intlayer/sync-json-plugin";

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    defaultLocale: Locales.ENGLISH,
  },

  // Поддерживайте синхронизацию ваших текущих JSON-файлов с словарями Intlayer
  plugins: [
    /**
     * Загрузит все JSON-файлы в src, которые соответствуют шаблону {key}.i18n.json
     */
    loadJSON({
      source: ({ key }) => `./src/**/${key}.i18n.json`,
      locale: Locales.ENGLISH,
      priority: 1, // Обеспечивает приоритет этих JSON-файлов над файлами в `./public/locales/en/${key}.json`
    }),
    /**
     * Загрузит, а также запишет результаты и переводы обратно в JSON-файлы в директории локалей
     */
    syncJSON({
      source: ({ key, locale }) => `./public/locales/${locale}/${key}.json`,
      priority: 0,
    }),
  ],
};

export default config;
```

Это загрузит все JSON-файлы в директории `src`, которые соответствуют шаблону `{key}.i18n.json`, и загрузит их как словари Intlayer.

---

## Конфигурация Git

Исключите сгенерированные файлы из системы контроля версий:

```plaintext fileName=".gitignore"
# Игнорировать файлы, сгенерированные Intlayer
.intlayer
```

Эти файлы автоматически пересоздаются во время процесса сборки и не требуют коммита в ваш репозиторий.

### Расширение VS Code

Для улучшения опыта разработчика установите официальное расширение **Intlayer для VS Code**:

[Установить из магазина расширений VS Code](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
