Налаштування 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% (за нашими даними, TTFB у 1.4 раза нижчий порівняно з i18next) та покращує Core Web Vitals. Бібліотека доступна на GitHub і, згідно з документацією, обробляє до 50 000 запитів на секунду на одному сервері.

Ця стаття охоплює ключові аспекти: next-intl налаштування, next-intl middleware, next-intl pathnames, next-intl typescript, next-intl статична генерація, next-intl RSC, next-intl конфігурація, hydration mismatch та SSR переклади. Ви дізнаєтесь про локалізацію React серверні компоненти за допомогою next-intl та i18n next js.

{ "home": { "title": "Головна", "description": "Ласкаво просимо" } } 

Які проблеми вирішуємо

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

Порівняння next-intl та i18next:

next-intl у 2 рази швидший за i18next у серверних компонентах за рахунок відсутності необхідності завантаження клієнтського JavaScript. Це підтверджено на проєктах із 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/ uk.json 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/Kyiv', now: new Date(), })); // src/middleware.ts import createMiddleware from 'next-intl/middleware'; export default createMiddleware({ locales: ['uk', 'ru', 'en', 'de'], defaultLocale: 'uk', localePrefix: 'as-needed', }); export const config = { matcher: ['/((?!api|_next|_vercel|.*\\..*).*)'], }; 

Типізація перекладів (TypeScript)

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

Тепер t('nonexistent.key') — помилка TypeScript.

Як next-intl працює в інтернет-магазині з 10 мовами?

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

Що важливо знати при налаштуванні локалізованих маршрутів

При використанні createLocalizedPathnamesNavigation потрібно задати шляхи для кожної мови. Це додає складності при статичній генерації, але next-intl вирішує її автоматично. Переконайтеся, що в messages немає конфліктів ключів.

Які етапи налаштування next-intl?

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 день. Вартість базового налаштування next-intl для 2-3 мов становить від $200, що дозволяє зекономити до 30% часу завантаження. Якщо потрібні локалізовані pathname, статична генерація та TypeScript-типізація — 2–3 дні.

Типові помилки та їх вирішення

Чому обирають нас

• Понад 5 років досвіду з Next.js та інтернаціоналізацією
• Гарантія підтримки та коректної роботи на всіх етапах
• Відкрита документація — всі налаштування фіксуються та передаються замовнику

Зв'яжіться з нами, щоб обговорити ваш проєкт — ми допоможемо налаштувати інтернаціоналізацію без болю. Отримайте консультацію прямо зараз.