Консоль

Смена языка

Как настроить и переключать языки в приложении Next.js

Переключение языка позволяет пользователям выбирать предпочитаемую локаль для контента вашего приложения. GT Next предлагает несколько подходов — от простого программного переключения до полноценной маршрутизации на основе URL с использованием middleware.

Доступные методы

Использование хука useSetLocale

Хук useSetLocale — это клиентский хук, который позволяет менять язык вашего приложения:

import { useSetLocale } from 'gt-next/client';

export default function MyComponent() {
  const setLocale = useSetLocale();

  return <button onClick={() => setLocale('en')}>Установить язык</button>;
}

Просто передайте нужную локаль в качестве аргумента функции, которую возвращает хук.

Использование компонента <LocaleSelector>

Компонент <LocaleSelector> — это готовый выпадающий список, который автоматически отображает все настроенные локали:

import { LocaleSelector } from 'gt-next/client';

export default function MyComponent() {
  return <LocaleSelector />;
}

Этот компонент автоматически:

  • Показывает все настроенные локали вашего проекта
  • Отображает локали на их родных языках
  • Обрабатывает переключение
  • Сохраняет текущий выбор

Использование хука useLocaleSelector

Если вы хотите создать собственный компонент выбора локали, используйте useLocaleSelector:

import { useLocaleSelector } from 'gt-next/client';

function CustomLocaleSelector() {
  const { 
    locale,              // Текущая активная локаль (напр., 'en', 'es')
    locales,             // Массив локалей, поддерживаемых проектом ['en', 'es', 'fr']
    setLocale,           // Функция для смены локали: setLocale('es')
    getLocaleProperties  // Функция для получения отображаемой информации о локали
  } = useLocaleSelector();
  
  if (!locales?.length) return null;
  
  return (
    <select 
      value={locale || ''} 
      onChange={(e) => setLocale(e.target.value)}
    >
      {locales.map((loc) => {
        const props = getLocaleProperties(loc);
        return (
          <option key={loc} value={loc}>
            {props.nativeNameWithRegionCode} {/* напр., "English (US)", "Español (ES)" */}
          </option>
        );
      })}
    </select>
  );
}

Переключение языка на основе URL

Для улучшения SEO и UX вы можете включать локаль в URL с помощью middleware‑маршрутизации. Подробнее об этом подходе — в руководстве по middleware:

/en/products  → страница товаров на английском  
/es/products  → страница товаров на испанском
/fr/products  → страница товаров на французском

Этот подход даёт преимущества для SEO, прямые ссылки на языковые версии и локализованные ссылки, которыми можно делиться.

Важные замечания

Только клиентские компоненты

Все хуки и компоненты для переключения языка должны использоваться в клиентских компонентах, помеченных директивой «use client»:

'use client';
import { useSetLocale } from 'gt-next/client';

function LanguageSwitcher() {
  const setLocale = useSetLocale();
  // ... логика компонента
}

Требование к GTProvider

Компоненты переключения языка должны использоваться внутри <GTProvider>:

// ✅ Правильно
<GTProvider>
  <LanguageSwitcher />
</GTProvider>

// ❌ Неправильно - за пределами провайдера
<LanguageSwitcher />

Дальнейшие шаги

Насколько полезно это руководство?

На этой странице

Доступные методы
Использование хука useSetLocale
Использование компонента <LocaleSelector>
Использование хука useLocaleSelector
Переключение языка на основе URL
Важные замечания
Только клиентские компоненты
Требование к GTProvider
Дальнейшие шаги
Смена языка