# General Translation React SDKs (gt-react, gt-next, gt-react-native): Управление локалями
URL: https://generaltranslation.com/ru/docs/react/guides/managing-locales.mdx
---

title: Управление локалями
description: Как настроить поддерживаемые локали, создать переключатель языка для React и определять или изменять активную локаль.
related:
  links:
    - /docs/react/guides/translating-jsx
    - /docs/react/guides/translating-strings
    - /docs/react/guides/configuring
    - /docs/react/guides/storing-translations

---

Коды локалей, такие как `en-US` и `fr`, связывают выбранный пользователем язык с нужными переводами и правилами форматирования.

Укажите поддерживаемые приложением локали, позвольте пользователям выбрать одну из них и определяйте активную локаль, когда вашему UI требуется поведение, зависящее от языка.

## Состояние локали [#locale-state]

* **Локаль по умолчанию:** язык, на котором написан исходный контент, а также окончательный резервный вариант, если ни одна из поддерживаемых локалей не подходит.
* **Поддерживаемые локали:** все локали, доступные пользователю для выбора, включая локаль по умолчанию и целевые локали.
* **Активная локаль:** поддерживаемая локаль, выбранная на основе URL, сохранённых предпочтений, настроек браузера или локали по умолчанию.

## Укажите поддерживаемые локали [#declare]

Укажите [`defaultLocale`](/docs/react/reference/config#default-locale) и перечислите целевые [`locales`](/docs/react/reference/config#locales) в `gt.config.json`:

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "fr", "de"]
}
```

В React, TanStack Start и React Native передайте эти значения в вызов инициализации. В Next.js [`withGTConfig`](/docs/react/nextjs/config) автоматически считывает `gt.config.json`. См. [Настройка General Translation](/docs/react/guides/configuring), чтобы узнать, как настроить каждый фреймворк.

## Добавление переключателя языка [#switcher]

Выберите наиболее простой вариант, подходящий для вашего интерфейса:

* Используйте [`<LocaleSelector>`](/docs/react/reference/components/locale-selector) — готовый выпадающий список для React, Next.js или TanStack Start.
* Используйте [`useLocaleSelector`](/docs/react/reference/hooks/use-locale-selector), чтобы создать собственный переключатель языка в любом поддерживаемом фреймворке.
* Используйте [`useSetLocale`](/docs/react/reference/hooks/use-set-locale) для кнопки или другого элемента управления, который переключает на заданную локаль.

### Используйте готовый селектор

Отрендерьте [`<LocaleSelector>`](/docs/react/reference/components/locale-selector) в клиентском компоненте. Без пропсов он выводит все настроенные локали и меняет активную локаль, когда пользователь выбирает нужный вариант.

<Tabs items={['React', 'Next.js', 'TanStack Start', 'React Native']}>
  <Tab value="React">
    ```tsx
    import { LocaleSelector } from 'gt-react';

    <LocaleSelector />;
    ```
  </Tab>

  <Tab value="Next.js">
    ```tsx
    import { LocaleSelector } from 'gt-next';

    <LocaleSelector />;
    ```
  </Tab>

  <Tab value="TanStack Start">
    ```tsx
    import { LocaleSelector } from 'gt-tanstack-start';

    <LocaleSelector />;
    ```
  </Tab>

  <Tab value="React Native">
    *Примечание: React Native не экспортирует [`<LocaleSelector>`](/docs/react/reference/components/locale-selector). Создайте собственный переключатель с помощью [`useLocaleSelector`](/docs/react/reference/hooks/use-locale-selector), как показано ниже.*
  </Tab>
</Tabs>

### Создайте пользовательский переключатель языка

[`useLocaleSelector`](/docs/react/reference/hooks/use-locale-selector) предоставляет активную локаль, доступные локали, функцию для её установки и локализованные отображаемые имена в одном хуке. Используйте элементы управления своего фреймворка:

<Tabs items={['React', 'Next.js', 'TanStack Start', 'React Native']}>
  <Tab value="React">
    ```tsx
    import { useLocaleSelector } from 'gt-react';

    function Switcher() {
      const { locale, locales, setLocale, getLocaleProperties } =
        useLocaleSelector();

      return (
        <select value={locale} onChange={(e) => setLocale(e.target.value)}>
          {locales.map((localeCode) => (
            <option key={localeCode} value={localeCode}>
              {getLocaleProperties(localeCode).nativeNameWithRegionCode}
            </option>
          ))}
        </select>
      );
    }
    ```
  </Tab>

  <Tab value="Next.js">
    ```tsx
    'use client';

    import { useLocaleSelector } from 'gt-next';

    function Switcher() {
      const { locale, locales, setLocale, getLocaleProperties } =
        useLocaleSelector();

      return (
        <select value={locale} onChange={(e) => setLocale(e.target.value)}>
          {locales.map((localeCode) => (
            <option key={localeCode} value={localeCode}>
              {getLocaleProperties(localeCode).nativeNameWithRegionCode}
            </option>
          ))}
        </select>
      );
    }
    ```
  </Tab>

  <Tab value="TanStack Start">
    ```tsx
    import { useLocaleSelector } from 'gt-tanstack-start';

    function Switcher() {
      const { locale, locales, setLocale, getLocaleProperties } =
        useLocaleSelector();

      return (
        <select value={locale} onChange={(e) => setLocale(e.target.value)}>
          {locales.map((localeCode) => (
            <option key={localeCode} value={localeCode}>
              {getLocaleProperties(localeCode).nativeNameWithRegionCode}
            </option>
          ))}
        </select>
      );
    }
    ```
  </Tab>

  <Tab value="React Native">
    ```tsx
    import { Button, View } from 'react-native';
    import { useLocaleSelector } from 'gt-react-native';

    function Switcher() {
      const { locale, locales, setLocale, getLocaleProperties } =
        useLocaleSelector();

      return (
        <View>
          {locales.map((localeCode) => (
            <Button
              key={localeCode}
              title={getLocaleProperties(localeCode).nativeNameWithRegionCode}
              disabled={localeCode === locale}
              onPress={() => setLocale(localeCode)}
            />
          ))}
        </View>
      );
    }
    ```
  </Tab>
</Tabs>

Если в веб-приложении на React вам нужно только напрямую изменить локаль, вызовите [`useSetLocale`](/docs/react/reference/hooks/use-set-locale):

```tsx
import { useSetLocale } from 'gt-react';

function FrenchButton() {
  const setLocale = useSetLocale();
  return <button onClick={() => setLocale('fr')}>Français</button>;
}
```

## Сохранение выбора локали и маршрутизация [#persistence]

При изменении локали через [`<LocaleSelector>`](/docs/react/reference/components/locale-selector), [`useLocaleSelector`](/docs/react/reference/hooks/use-locale-selector) или [`useSetLocale`](/docs/react/reference/hooks/use-set-locale) выбор сохраняется, а новые переводы применяются по-разному в зависимости от фреймворка:

* **React:** сохраняет локаль в cookie-файле, а затем по умолчанию перезагружает страницу. Пользовательский callback перезагрузки provider может заменить полную перезагрузку страницы.
* **Next.js App Router:** сохраняет локаль в cookie-файле, а затем обновляет дерево серверных компонентов. Middleware для локалей применяет настроенную маршрутизацию путей.
* **Next.js Pages Router:** сохраняет локаль в cookie-файле. Настройте callback перезагрузки provider для навигации через Pages Router и получения пропсов страницы для выбранной локали.
* **TanStack Start:** сохраняет локаль в cookie-файле, а затем перезагружает страницу. При включённом [`localeRouting`](/docs/react/reference/config#locale-routing) выполняется переход к pathname соответствующей локали.
* **React Native:** сохраняет локаль в нативном хранилище (или `localStorage` в React Native Web), обновляет состояние provider, загружает переводы для локали и выполняет повторный рендеринг без навигации в браузере.

Для публичных страниц URL-адреса на основе локали делают каждую языковую версию доступной по ссылке и индексируемой. Настройте маршрутизацию в руководстве для соответствующего фреймворка:

* [Middleware Next.js App Router](/docs/react/nextjs/app-router-middleware)
* [Маршрутизация по локалям Next.js Pages Router](/docs/react/nextjs/pages-router-middleware)
* [Маршрутизация по локалям TanStack Start](/docs/react/tanstack-start/setup#locale-routing)

## Чтение активной локали [#read]

Используйте хуки локали при рендеринге UI, зависящего от языка:

* [`useLocale`](/docs/react/reference/hooks/use-locale) возвращает код активной локали.
* [`useDefaultLocale`](/docs/react/reference/hooks/use-default-locale) возвращает исходную локаль.
* [`useLocales`](/docs/react/reference/hooks/use-locales) возвращает все коды поддерживаемых локалей.
* [`useLocaleDirection`](/docs/react/reference/hooks/use-locale-direction) возвращает `'ltr'` или `'rtl'` для определения направления страницы.
* [`useLocaleProperties`](/docs/react/reference/hooks/use-locale-properties) возвращает имя локали, её название на родном языке, регион, систему письма и другие метаданные для отображения.

*Примечание: `gt-tanstack-start` пока не экспортирует [`useLocaleDirection`](/docs/react/reference/hooks/use-locale-direction) и [`useLocaleProperties`](/docs/react/reference/hooks/use-locale-properties). Вместо них получайте метаданные локали через [`getLocaleProperties`](/docs/platform/core/reference/utility-functions/locales/get-locale-properties) из `generaltranslation`.*

В Next.js эти хуки работают в синхронных серверных компонентах App Router. В асинхронных компонентах вызывайте [`getLocale`](/docs/react/nextjs/reference/functions/get-locale) и [`getLocaleDirection`](/docs/react/nextjs/reference/functions/get-locale-direction) из `gt-next/server`:

```tsx
import { getLocale, getLocaleDirection } from 'gt-next/server';

async function Layout() {
  const locale = await getLocale();
  const dir = await getLocaleDirection();
  return <html lang={locale} dir={dir} />;
}
```

Сведения о сопоставлении локалей и резервном варианте см. на странице [справочника `useLocale`](/docs/react/reference/hooks/use-locale).
## Next steps

- /docs/react/guides/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/configuring
- /docs/react/guides/storing-translations