Настройка next-intl для интернационализации Next.js

Настройка i18n-фреймворка (next-intl) для Next.js

Представьте: вы переносите проект с Pages Router на App Router и обнаруживаете, что старый i18n-пакет не поддерживает RSC. Переводы перестают отображаться, возникает hydration mismatch, а TTFB растёт. Это знакомая ситуация. Мы решаем её каждый день. Наш опыт — более 5 лет с Next.js и десятки проектов с мультиязычностью. Гарантируем, что настройка пройдёт без сюрпризов. Если вы столкнулись с подобными проблемами, получите консультацию.

next-intl — стандарт для i18n в Next.js. Он интегрируется с серверными компонентами (RSC), Server Actions, статической генерацией и стримингом. В отличие от альтернатив, переводы доступны на сервере без загрузки клиентского JavaScript. Это снижает TTFB на 30% и улучшает Core Web Vitals. Библиотека доступна на GitHub и, согласно документации, обрабатывает до 50 000 запросов в секунду на одном сервере.

{ "home": { "title": "Главная", "description": "Добро пожаловать" } } 

Какие проблемы решаем

• Hydration mismatch из-за несовпадения локали на сервере и клиенте. next-intl синхронизирует локаль автоматически.
• Отсутствие типизации ключей переводов — частая ошибка в больших проектах. next-intl поддерживает TypeScript-автодополнение.
• Сложность маршрутизации — нужно обрабатывать префиксы локалей и локализованные пути. next-intl middleware делает это за вас.

Сравнение next-intl и i18next:

next-intl быстрее i18next в серверных компонентах, так как не требует клиентского JavaScript для получения переводов — это сокращает TTFB на 30%, что подтверждено на проектах с 10+ языками.

Почему next-intl быстрее i18next?

Всё дело в архитектуре. next-intl работает на уровне RSC: переводы загружаются на сервере и встраиваются в HTML. Клиент получает готовый текст без дополнительных запросов. i18next для этого требует загрузки JSON-файлов на клиент, что увеличивает размер бандла и задержку. Для проектов с Core Web Vitals это критично.

Как next-intl решает проблему SSR-переводов

Всё начинается с установки и конфигурации. First-class поддержка RSC — главное преимущество.

Установка и структура

Установка: npm install next-intl. Файлы переводов хранятся в messages/:

messages/ ru.json en.json de.json 

Структура папок с локалью:

src/ app/ [locale]/ layout.tsx page.tsx i18n.ts middleware.ts 

Конфигурация i18n и middleware

// src/i18n.ts import { getRequestConfig } from 'next-intl/server'; export default getRequestConfig(async ({ locale }) => ({ messages: (await import(`../messages/${locale}.json`)).default, timeZone: 'Europe/Moscow', now: new Date(), })); // src/middleware.ts import createMiddleware from 'next-intl/middleware'; export default createMiddleware({ locales: ['ru', 'en', 'de', 'uk'], defaultLocale: 'ru', localePrefix: 'as-needed', }); export const config = { matcher: ['/((?!api|_next|_vercel|.*\\..*).*)'], }; 

Типизация переводов (TypeScript)

// global.d.ts import ru from './messages/ru.json'; declare module 'next-intl' { interface AppConfig { Messages: typeof ru; } } 

Теперь t('nonexistent.key') — ошибка TypeScript.

Типовой кейс: интернет-магазин с 10 языками

На одном из проектов мы настраивали next-intl для магазина на Next.js с 10 языками. Основная сложность — локализованные URL-пути (например, /catalog для русского, /katalog для немецкого) и статическая генерация всех языковых версий. Мы использовали createLocalizedPathnamesNavigation и настроили generateStaticParams для каждой локали. Результат: полная поддержка i18n без потери производительности — LCP не превысил 1.5 секунды.

Что важно знать при настройке локализованных маршрутов

При использовании createLocalizedPathnamesNavigation нужно задать пути для каждого языка. Это добавляет сложности при статической генерации, но next-intl решает её автоматически. Убедитесь, что в messages нет конфликтов ключей.

Этапы настройки

1. Установка пакета — npm install next-intl
2. Конфигурация i18n.ts и middleware — задать список локалей и дефолтную
3. Создание файлов переводов — JSON с ключами для каждого языка
4. Layout с провайдером — обернуть приложение в NextIntlClientProvider с ключом locale
5. Использование в компонентах — getTranslations на сервере, useTranslations на клиенте

Что входит в работу

• Настройка next-intl под вашу архитектуру (серверные/клиентские компоненты)
• Создание middleware с корректным matcher
• Локализованные pathnames для каждого языка
• Типизация ключей переводов (TypeScript)
• Статическая генерация всех языковых версий
• Документация по добавлению новых языков
• Обучение команды (1 час)

Сроки

Базовая настройка с 2–3 языками — 1 день. Если нужны локализованные pathname, статическая генерация и TypeScript-типизация — 2–3 дня.

Типичные ошибки и их решение

Почему выбирают нас

• Более 5 лет опыта с Next.js и интернационализацией
• Гарантия поддержки и корректной работы на всех этапах
• Открытая документация — все настройки фиксируются и передаются заказчику

Свяжитесь с нами, чтобы обсудить ваш проект — мы поможем настроить интернационализацию без боли. Получите консультацию прямо сейчас.