Спросите свой вопрос и получите сводку документа, используя эту страницу и выбранного вами поставщика AI
История версий
- Начальная версияv7.0.001.11.2025
Содержимое этой страницы было переведено с помощью ИИ.
Смотреть последнюю версию оригинального контента на английскомЕсли у вас есть идея по улучшению этой документации, не стесняйтесь внести свой вклад, подав запрос на вытягивание на GitHub.
Ссылка на документацию GitHubКопировать Markdown документа в буфер обмена
Как интернационализировать ваше приложение Next.js с помощью next-intl в 2025 году
Содержание
Что такое next-intl?
next-intl, это популярная библиотека интернационализации (i18n), разработанная специально для Next.js App Router. Она обеспечивает бесшовный способ создания многоязычных приложений Next.js с отличной поддержкой TypeScript и встроенными оптимизациями.
Если хотите, вы также можете ознакомиться с руководством по next-i18next или использовать напрямую Intlayer.
Сравнение доступно в статье next-i18next vs next-intl vs Intlayer.
Практики, которые следует соблюдать
Прежде чем перейти к реализации, вот несколько рекомендаций, которым следует следовать:
- Установите атрибуты HTML
langиdir
В вашем layout вычисляйтеdirс помощьюgetLocaleDirection(locale)и задавайте<html lang={locale} dir={dir}>для правильной доступности и SEO. - Разделяйте сообщения по namespace
Организуйте JSON-файлы по локалям и namespace (например,common.json,about.json), чтобы загружать только необходимое. - Минимизируйте нагрузку на клиент
На страницах отправляйте вNextIntlClientProviderтолько необходимые namespace (например,pick(messages, ['common', 'about'])). - Предпочитайте статические страницы
Используйте статические страницы по максимуму для лучшей производительности и SEO. - Интернационализация в серверных компонентах
Компоненты сервера, такие как страницы или все компоненты, не помеченные какclient, являются статическими и могут быть предварительно отрендерены во время сборки. Поэтому нам нужно будет передавать функции перевода им через props. - Настройте типы TypeScript
Для ваших локалей, чтобы обеспечить типобезопасность во всем приложении. - Прокси для перенаправления
Используйте прокси для обработки определения локали и маршрутизации, а также для перенаправления пользователя на соответствующий URL с префиксом локали. - Интернационализация ваших метаданных, sitemap, robots.txt
Интернационализируйте ваши метаданные, sitemap, robots.txt с помощью функцииgenerateMetadata, предоставляемой Next.js, чтобы обеспечить лучшее обнаружение страниц поисковыми системами во всех локалях. - Локализация ссылок
Локализуйте ссылки, используя компонентLink, чтобы перенаправлять пользователя на URL с соответствующим префиксом локали. Это важно для обеспечения обнаружения ваших страниц во всех локалях. - Автоматизация тестов и переводов
Автоматизация тестов и переводов помогает экономить время на поддержку вашего многоязычного приложения.
См. нашу документацию, в которой перечислено все, что нужно знать об интернационализации и SEO: Интернационализация (i18n) с next-intl.
Пошаговое руководство по настройке next-intl в приложении Next.js
См. Шаблон приложения на GitHub.
Вот структура проекта, которую мы будем создавать:
Копировать код в буфер обмена
Установка зависимостей
Установите необходимые пакеты с помощью npm:
bashКопировать кодКопировать код в буфер обмена
- next-intl: Основная библиотека интернационализации для Next.js App Router, предоставляющая хуки, серверные функции и клиентские провайдеры для управления переводами.
Настройка проекта
Создайте файл конфигурации, который определяет поддерживаемые локали и настраивает конфигурацию запросов next-intl. Этот файл служит единственным источником правды для вашей настройки i18n и обеспечивает типобезопасность во всём приложении.
Централизация конфигурации локалей предотвращает несоответствия и упрощает добавление или удаление локалей в будущем. Функция
getRequestConfigвыполняется при каждом запросе и загружает только те переводы, которые необходимы для каждой страницы, что позволяет использовать разделение кода и уменьшать размер бандла.src/i18n.tsКопировать кодКопировать код в буфер обмена
Определение динамических маршрутов локалей
Настройте динамическую маршрутизацию для локалей, создав каталог
[locale]в вашей папке приложения. Это позволяет Next.js обрабатывать маршрутизацию на основе локали, где каждая локаль становится сегментом URL (например,/en/about,/fr/about).Использование динамических маршрутов позволяет Next.js генерировать статические страницы для всех локалей во время сборки, что улучшает производительность и SEO. Компонент layout устанавливает атрибуты HTML
langиdirна основе локали, что важно для доступности и понимания поисковыми системами.src/app/[locale]/layout.tsxКопировать кодКопировать код в буфер обмена
src/app/[locale]/about/page.tsxКопировать кодКопировать код в буфер обмена
Создайте файлы переводов
Создайте JSON-файлы для каждой локали и пространства имён. Такая структура позволяет логично организовать переводы и загружать только то, что необходимо для каждой страницы.
Организация переводов по пространствам имён (например,
common.json,about.json) позволяет использовать разделение кода (code splitting) и уменьшает размер бандла. Вы загружаете только переводы, необходимые для каждой страницы, что улучшает производительность.locales/en/common.jsonКопировать кодКопировать код в буфер обмена
locales/fr/common.jsonКопировать кодКопировать код в буфер обмена
locales/en/about.jsonКопировать кодКопировать код в буфер обмена
locales/fr/about.jsonКопировать кодКопировать код в буфер обмена
Используйте переводы на своих страницах
Создайте компонент страницы, который загружает переводы на сервере и передает их как серверным, так и клиентским компонентам. Это гарантирует, что переводы загружены до рендеринга и предотвращает мерцание контента.
Загрузка переводов на стороне сервера улучшает SEO и предотвращает FOUC (Flash of Untranslated Content, мерцание непереведенного контента). Используя
pickдля передачи только необходимых пространств имен клиентскому провайдеру, мы минимизируем размер JavaScript-бандла, отправляемого в браузер.src/app/[locale]/about/page.tsxКопировать кодКопировать код в буфер обмена
Использование переводов в клиентских компонентах
Клиентские компоненты могут использовать хуки
useTranslationsиuseFormatterдля доступа к переводам и функциям форматирования. Эти хуки читают данные из контекстаNextIntlClientProvider.Клиентским компонентам необходимы React хуки для доступа к переводам. Хуки
useTranslationsиuseFormatterинтегрируются с next-intl и обеспечивают реактивное обновление при изменении локали.Не забудьте добавить необходимые пространства имён в клиентские сообщения страницы (включайте только те пространства имён, которые действительно нужны вашим клиентским компонентам).
src/components/ClientComponent.tsxКопировать кодКопировать код в буфер обмена
Использование переводов в серверных компонентах
Серверные компоненты не могут использовать React хуки, поэтому они получают переводы и форматтеры через props от родительских компонентов. Такой подход сохраняет серверные компоненты синхронными и позволяет вкладывать их внутрь клиентских компонентов.
Компоненты сервера, которые могут быть вложены в клиентские границы, должны быть синхронными. Передавая переведённые строки и отформатированные значения через props, мы избегаем асинхронных операций и обеспечиваем корректный рендеринг. Предварительно вычисляйте переводы и форматирование в родительском компоненте страницы.
src/components/ServerComponent.tsxКопировать кодКопировать код в буфер обмена
В вашем компоненте страницы/макета используйте
getTranslationsиgetFormatterизnext-intl/serverдля предварительного вычисления переводов и форматирования, затем передавайте их как пропсы в серверные компоненты.Изменение языка вашего контента
НеобязательноЧтобы изменить язык вашего контента с помощью next-intl, отображайте ссылки с учетом локали, которые указывают на тот же путь, но с переключением локали. Провайдер автоматически переписывает URL, поэтому вам нужно лишь указать текущий маршрут.
src/components/LocaleSwitcher.tsxКопировать кодКопировать код в буфер обмена
Использование локализованного компонента Link
Необязательноnext-intlпредоставляет подпакетnext-intl/navigation, который содержит локализованный компонент ссылки, автоматически применяющий активную локаль. Мы уже вынесли его для вас в файл@/i18n, так что вы можете использовать его следующим образом:src/components/MyComponent.tsxКопировать кодКопировать код в буфер обмена
Доступ к активной локали внутри Server Actions
НеобязательноServer Actions могут читать текущую локаль с помощью
next-intl/server. Это полезно для отправки локализованных писем или сохранения языковых предпочтений вместе с отправленными данными.src/app/actions/get-current-locale.tsКопировать кодКопировать код в буфер обмена
getLocaleчитает локаль, установленную проксиnext-intl, поэтому работает в любом месте на сервере: Route Handlers, Server Actions и edge functions.Интернационализация ваших метаданных
НеобязательноПеревод контента важен, но главная цель интернационализации, сделать ваш сайт более заметным для всего мира. I18n, это невероятный рычаг для улучшения видимости вашего сайта через правильное SEO.
Правильно интернационализированные метаданные помогают поисковым системам понять, какие языки доступны на ваших страницах. Это включает установку метатегов hreflang, перевод заголовков и описаний, а также обеспечение корректной установки канонических URL для каждой локали.
src/app/[locale]/about/layout.tsxКопировать кодКопировать код в буфер обмена
Интернационализация вашей карты сайта
НеобязательноСоздайте sitemap, который включает все локализованные версии ваших страниц. Это помогает поисковым системам обнаруживать и индексировать все языковые версии вашего контента.
Правильно интернационализированный sitemap гарантирует, что поисковые системы смогут найти и индексировать все языковые версии ваших страниц. Это улучшает видимость в международных результатах поиска.
src/app/sitemap.tsКопировать кодКопировать код в буфер обмена
Интернационализация вашего файла robots.txt
НеобязательноСоздайте файл robots.txt, который корректно обрабатывает все языковые версии ваших защищённых маршрутов. Это гарантирует, что поисковые системы не будут индексировать страницы админки или панели управления на любом языке.
Правильная настройка robots.txt для всех локалей предотвращает индексацию поисковыми системами чувствительных страниц, когда ваши маршруты отличаются для каждой локали.
src/app/robots.tsКопировать кодКопировать код в буфер обмена
Настройка прокси для маршрутизации по локали
НеобязательноСоздайте прокси, который автоматически определяет предпочитаемую пользователем локаль и перенаправляет его на соответствующий URL с префиксом локали. next-intl предоставляет удобную функцию прокси, которая обрабатывает это автоматически.
Прокси обеспечивает автоматическое перенаправление пользователей на предпочитаемый ими язык при посещении вашего сайта. Он также сохраняет предпочтения пользователя для будущих посещений, улучшая пользовательский опыт.
src/proxy.tsКопировать кодКопировать код в буфер обмена
Настройка типов TypeScript для локали
НеобязательноНастройка TypeScript поможет вам получить автодополнение и типобезопасность для ваших ключей.
Для этого вы можете создать файл global.ts в корне вашего проекта и добавить следующий код:
global.tsКопировать кодКопировать код в буфер обмена
Этот код использует расширение модуля (Module Augmentation), чтобы добавить локали и сообщения в тип AppConfig из next-intl.
Автоматизация переводов с помощью Intlayer
НеобязательноIntlayer, это бесплатная и открытая библиотека, предназначенная для помощи в процессе локализации вашего приложения. В то время как next-intl отвечает за загрузку и управление переводами, Intlayer помогает автоматизировать рабочий процесс перевода.
Управление переводами вручную может занимать много времени и быть подвержено ошибкам. Intlayer автоматизирует тестирование, генерацию и управление переводами, экономя ваше время и обеспечивая согласованность по всему приложению.
Intlayer позволяет вам:
Объявлять ваш контент там, где вы хотите, в вашей кодовой базе
Intlayer позволяет объявлять ваш контент там, где вы хотите, в вашей кодовой базе, используя файлы.content.{ts|js|json}. Это обеспечит лучшую организацию вашего контента, улучшая читаемость и поддерживаемость вашей кодовой базы.Тестировать отсутствующие переводы
Intlayer предоставляет функции тестирования, которые можно интегрировать в ваш CI/CD pipeline или в ваши модульные тесты. Узнайте больше о тестировании ваших переводов.Автоматизация ваших переводов
Intlayer предоставляет CLI и расширение для VSCode для автоматизации ваших переводов. Это можно интегрировать в ваш CI/CD pipeline. Узнайте больше о автоматизации ваших переводов.
Вы можете использовать свой собственный API-ключ и выбранного вами AI-провайдера. Также поддерживаются контекстно-зависимые переводы, см. заполнение контента.Подключение внешнего контента
Intlayer позволяет подключать ваш контент к внешней системе управления контентом (CMS). Для оптимального получения данных и вставки их в ваши JSON-ресурсы. Узнайте больше о получении внешнего контента.Визуальный редактор
Intlayer предлагает бесплатный визуальный редактор для редактирования вашего контента с помощью визуального интерфейса. Узнайте больше о визуальном редактировании ваших переводов.
И многое другое. Чтобы узнать обо всех функциях, предоставляемых Intlayer, пожалуйста, обратитесь к документации о преимуществах Intlayer.
Комментарии
Пока нет комментариев. Будьте первым, кто поделится своими мыслями.