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

Почему локализация ломает маршрутизацию и метаданные

Когда в проект добавляют вторую локаль, ломается не перевод, а маршрутизация. Появляется параллельное дерево путей, и дальше всё зависит от того, где именно вы решаете, какой язык показывать: в посреднике запроса, в раскладке или внутри компонента. Если решение принимается в трёх местах сразу, получаете конфликт маршрутов — часть адресов отдаёт не ту локаль, часть редиректит по кругу, а внутренние ссылки ведут на язык, которого пользователь не выбирал.

Вторая типичная поломка — дубли canonical. Пока страница живёт по одному адресу, канонический тег собирается тривиально. С мультиязычным роутингом та же сущность доступна по нескольким путям, и если canonical и hreflang формируются в разных слоях, поисковик видит конкурирующие версии одной страницы. Исправляется это не правкой шаблона, а единым источником правды: локаль и путь должны вычисляться из одного места, а альтернативные адреса — генерироваться из того же списка локалей, что и маршруты.

Третий сбой заметен позже всего: перевод теряется в серверных компонентах. Клиентская часть язык подхватывает, а серверный рендер отдаёт текст локали по умолчанию — в разметке оказывается смесь языков, и это бьёт и по выдаче, и по восприятию. Причина в том, что словари подгружаются асинхронно и не всегда доступны на этапе рендера на сервере.

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

Что даёт корректная интернационализация

Корректная настройка next-intl убирает главную боль мультиязычных сайтов — рассинхрон между маршрутами, словарями и разметкой. Когда локали, префиксы путей и заголовок hreflang генерируются из одного источника, каждая языковая версия получает собственный канонический адрес. Поисковик видит не дубли, а связанные страницы, и выдача перестаёт «съедать» переводы в пользу основного языка.

Скорость добавления языка перестаёт зависеть от размера проекта. Новый словарь подключается как отдельный файл с плоской структурой ключей, маршруты подхватывают локаль автоматически, а middleware определяет язык по заголовку запроса и cookie. На практике это превращает запуск языка из многонедельного проекта в задачу на несколько дней — без переписывания компонентов.

Рост словарей — типичная точка отказа. При сотнях ключей ручной поиск пропущенных переводов не работает, поэтому в сборку встраивается проверка: отсутствующий ключ ломает сборку, а не тихо рендерится пустой строкой на проде. Такой контроль держит словари в согласованном состоянии, даже когда над переводами работает несколько человек параллельно.

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

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

Сравнение подходов к мультиязычности

Выбор инструмента мультиязычности определяет, сколько ручной работы останется команде после запуска первого языка. На практике решают между тремя вариантами: собственные словари, сторонняя библиотека и next-intl — каждый закрывает свой класс задач и имеет границы, за которыми начинает мешать.

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

Сторонние библиотеки закрывают сложную лингвистику, но добавляют слой абстракции между приложением и фреймворком. Каждое обновление Next.js превращается в проверку совместимости, а серверные компоненты требуют обходных решений.

next-intl встраивается в маршрутизацию и рендеринг Next.js напрямую: языковой сегмент в URL, словари на сервере, форматирование дат и чисел по локали. Ограничение одно — инструмент рассчитан именно на этот стек, и вне его преимущества теряются.

Как проходит next-intl настройка в проекте

Настройка интернационализации в Next.js — это не «подключить библиотеку», а спроектировать маршрутизацию, словари и поведение при переключении языка так, чтобы ни один язык не ломал SEO и не терял контент. Работаем по этапам, каждый заканчивается проверяемым результатом.

1. Аудит текущей локализации. Смотрим, как устроены тексты сейчас: зашиты в компоненты, лежат в разрозненных файлах или уже вынесены в словари. Фиксируем языки, которые реально нужны, и места, где контент подставляется динамически — именно там чаще всего всплывают непереведённые строки.
2. Проектирование схемы маршрутов. Определяем, будет ли локаль в пути (/en/..., /de/...) или в поддомене, задаём локаль по умолчанию и правила редиректов. От этой схемы зависит индексация: каждый язык должен иметь собственный адрес и корректный hreflang.
3. Подключение словарей. Разбиваем переводы по пространствам имён — общие, страничные, служебные — и настраиваем загрузку только нужного набора для конкретного маршрута. Так размер передаваемых данных не растёт вместе с числом языков.
4. Перевод интерфейса и контента. Заменяем зашитые строки на ключи, отдельно проходим форматы дат, чисел и множественных форм — они в разных языках ведут себя по-разному и требуют явных правил, а не шаблонной подстановки.
5. Проверка на всех языках. Прогоняем каждый маршрут в каждой локали: переключение языка, прямые ссылки, редиректы, отсутствующие ключи. Отдельно смотрим, что при смене языка пользователь остаётся на той же странице, а не падает на главную.
6. Передача документации. Отдаём схему маршрутов, структуру словарей, правила добавления нового языка и чек-лист проверки. Команда заказчика дальше расширяет локализацию без нашего участия.

Ключевой принцип: новый язык добавляется правкой конфигурации и файла переводов, а не переписыванием маршрутов. Если для запуска локали нужно трогать код страниц — схема спроектирована неверно, и мы это исправляем до передачи.

Артефакты после внедрения интернационализации

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

• Конфигурация маршрутизации и локалей. Файл настроек с перечнем языков, локалью по умолчанию и стратегией префиксов: /en/catalog против catalog с определением языка по заголовку запроса. Отдельно зафиксировано поведение для корня сайта и для несуществующих локалей — редирект или страница 404.
• Схема маршрутов. Таблица соответствия «публичный адрес → файл страницы → словарь», включая вложенные сегменты и динамические части. По ней новый разработчик понимает структуру за минуты, а не восстанавливает её по коду.
• Словари сообщений. Разложены по пространствам имён: общие тексты интерфейса, страницы, письма, системные ошибки. Формат единый для всех языков, ключи не дублируются между файлами.
• Регламент обновления переводов. Описан порядок: кто правит исходный язык, как изменения попадают к переводчику, что происходит с ключами, которых нет в целевом языке. Указано поведение приложения при отсутствующем переводе — подстановка исходного текста вместо пустой строки.
• Проверки целостности. Автоматическая сверка словарей: расхождение ключей между языками и незадействованные строки ловятся до сборки, а не на проде.
• Документация для редакторов. Инструкция для контент-менеджера: где лежит текст, как добавить язык, что нельзя менять в ключах, чтобы не сломать разметку.
• Схема подключения новых языков. Пошаговый список: добавить локаль в конфигурацию, создать словарь, проверить маршруты и метаданные страниц. Один язык добавляется без правок в компоненты.

Комплект передаём вместе с разбором: показываем, где что лежит и как проверить результат локально. Опишите задачу — вернёмся с оценкой и планом по вашему стеку.

Кейс: ускорение вывода нового языка в 4 раза

Проект — маркетплейс услуг с каталогом, личным кабинетом и потоком пользовательских уведомлений. Интерфейс жил на трёх языках, и каждый новый рынок запускался вручную: разработчики копировали страницы под новую локаль, строки правили прямо в разметке, а часть текстов подтягивалась из базы без привязки к языку. На четвёртый язык ушло три недели, и почти сразу посыпались ошибки локализации — непереведённые блоки, «съехавшие» даты и числа, письма на языке предыдущего пользователя.

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

Мы перевели проект на next-intl и вынесли весь текст в словари по локалям: строки больше не живут в разметке, а подключаются по ключу. Маршрутизация получила единый префикс языка, для каждой страницы автоматически формируется канонический адрес и карта языковых версий — дубли закрылись на уровне генерации. Форматирование дат, чисел и валют отдано встроенным средствам с привязкой к локали, поэтому региональные настройки больше не зависят от того, кто и где открыл страницу.

Что изменилось в цифрах

Ускорение в четыре раза дала не сама библиотека, а порядок, который она навязывает: один источник текста, единая схема адресов, автоматическое форматирование. Добавление языка теперь сводится к новому словарю и одной строке конфигурации — инженер не переписывает страницы и не рискует задеть логику.

Чем next-intl отличается от ручной локализации?

Ручная локализация начинается с безобидного словаря в отдельном файле, но живёт ровно до первого расхождения между языками. Дальше появляются ключи, которые есть в английском и забыты в немецком, строки с подстановкой вида Привет, {name}, собранные конкатенацией, и даты, отформатированные вручную под каждый рынок. Ошибки при этом не падают на сборке — они всплывают у пользователя, который видит пустое место вместо текста или английскую фразу посреди немецкой страницы.

next-intl переворачивает эту модель: переводы становятся типизированным ресурсом, а не набором строк. Ключи описываются один раз, и обращение к несуществующему ключу ломает сборку, а не продакшен — забытый перевод в новой языковой ветке ловится до релиза. Автоподстановка значений работает через явные параметры, поэтому порядок слов в разных языках не приходится подгонять вручную: шаблон описывает смысл, а не позицию.

Отдельная боль ручного подхода — склонения и формы множественного числа. В русском «1 товар», «2 товара», «5 товаров» — три разные формы, в арабском их шесть, и разбор этого через условия в коде быстро превращается в нечитаемую ветвистую логику. Библиотека берёт правила из стандартных данных локали и сама выбирает нужную форму по числу, а разработчик пишет один шаблон вместо набора условий.

На уровне поддержки разница ещё заметнее. При ручной локализации добавление языка — это ревизия всего кода на предмет зашитых строк, а изменение текста требует синхронной правки нескольких файлов. С next-intl новый язык подключается конфигурацией и файлом переводов, а структура ключей остаётся общей: правка в одном месте не расходится по веткам. Именно поэтому на проектах с двумя и более языками ручная локализация со временем дорожает с каждым релизом, а подход через next-intl — нет.

Технические сомнения по интернационализации

Разберём три технических сомнения, которые чаще всего всплывают при настройке next-intl: скорость, кэширование и работа с динамическим контентом. Ниже — короткие ответы с механикой, а не общие слова.

Как кэшировать страницы, если язык зависит от URL?

Локаль — часть пути, а значит каждая языковая версия кэшируется отдельно и независимо. Это позволяет отдавать статику из кэша на всём маршруте, не смешивая языки. Для страниц с персонализацией мы разделяем статическую оболочку и динамические данные: оболочка кэшируется по локали, а пользовательские блоки подгружаются отдельно. Так кэш остаётся эффективным, а контент — актуальным.

Что делать с динамическим контентом и переводами из базы?

Строки, которые меняются без релиза, храним в базе или в системе управления контентом и подтягиваем по ключу. Статические тексты интерфейса остаются в словарях, а редактируемые — в источнике данных. На этапе сборки проверяем, что все ключи переведены: если ключа нет, сборка падает, а не отдаёт пустоту в продакшене. Это убирает класс ошибок, когда на одном языке текст есть, а на другом — пустой блок.

Можно ли добавить новый язык без переписывания кода?

Да. Добавление локали — это новый файл словаря и одна строка в конфигурации маршрутов. Компоненты и логика остаются нетронутыми, потому что работают с ключами, а не с текстом напрямую. Мы заранее закладываем структуру ключей так, чтобы порядок слов и падежи в разных языках не ломали вёрстку.

Если остались сомнения по вашему стеку — опишите задачу, вернёмся с оценкой и планом.

Обсудим вашу задачу по локализации

Чтобы вернуться с оценкой и планом работ по локализации, нам нужен минимум контекста о вашем приложении — дальше разберёмся сами. Опишите задачу в свободной форме: какие языки и регионы нужны, есть ли уже переводы, как устроена маршрутизация и откуда берутся тексты. Этого достаточно, чтобы оценить объём и предложить схему.

Что помогает ускорить старт проекта:

• Список целевых локалей и приоритет между ними — от него зависит структура маршрутов и порядок вычитки.
• Текущее состояние текстов: где они лежат сейчас — в разметке, в базе, в файлах переводов или в таблицах у переводчиков.
• Требования к форматам дат, чисел, валют и единиц измерения по регионам — их обычно забывают, а они ломают интерфейс сильнее всего.
• Наличие готовых переводов и глоссария терминов, чтобы не переводить заново то, что уже согласовано.
• Доступ к репозиторию и стенду: посмотрим, как устроена сборка, и предложим схему подключения без переписывания приложения.
• Ограничения по срокам и релизам — под них выстроим порядок работ, чтобы локализация не блокировала текущие задачи.

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

Опишите задачу — вернёмся с оценкой, планом работ и предложением по срокам. Если удобно, приложите ссылку на приложение или скриншоты ключевых экранов: так оценка будет точнее.