# General Translation React SDKs (gt-react, gt-next, gt-react-native): 管理区域设置
URL: https://generaltranslation.com/zh/docs/react/guides/managing-locales.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 介绍如何配置支持的区域设置、构建 React 语言切换器，以及读取或更改当前生效的区域设置。

区域设置代码 (如 `en-US` 和 `fr`) 可将用户的语言选择关联到相应的翻译和格式化规则。

声明你的应用支持的区域设置，让用户选择其中一种，并在 UI 需要特定语言行为时读取当前生效的区域设置。

## 了解区域设置状态 [#locale-state]

* **默认区域设置：**源内容使用的语言；当没有任何受支持的区域设置匹配时，作为最终后备内容。
* **受支持的区域设置：**用户可选择的所有区域设置，包括默认区域设置和目标区域设置。
* **当前生效的区域设置：**根据 URL、已保存的偏好设置、浏览器设置或默认值确定的受支持区域设置。

## 声明支持的区域设置 [#declare]

在 `gt.config.json` 中设置 [`defaultLocale`](/docs/react/reference/config#default-locale)，并列出目标 [`locales`](/docs/react/reference/config#locales)：

```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`。各框架的 setup 方式请参阅[配置 General Translation](/docs/react/guides/configuring)。

## 添加语言切换器 [#switcher]

选择最适合您界面的简便方式：

* 在 React、Next.js 或 TanStack Start 中，使用 [`<LocaleSelector>`](/docs/react/reference/components/locale-selector) 添加现成的下拉菜单。
* 使用 [`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 Web 应用中只需直接设置区域设置，请调用 [`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 中，然后默认重新加载页面。自定义 provider 重新加载回调可替代整页重新加载。
* **Next.js App Router：**将区域设置存储在 cookie 中，然后通常刷新服务器组件树。启用区域设置路由后，从解析为非默认区域设置的 URL 切换到默认区域设置时，会重新加载文档，以便中间件移除区域设置前缀。已解析为默认区域设置的 URL 则只会刷新。
* **Next.js Pages Router：**将区域设置存储在 cookie 中。配置 provider 重新加载回调，以便通过 Pages Router 导航并获取所选区域设置的页面属性。
* **TanStack Start：**将区域设置存储在 cookie 中，然后重新加载页面。启用 [`localeRouting`](/docs/react/reference/config#locale-routing) 后，它会导航到相应区域设置的 pathname。
* **React Native：**将区域设置存储在原生存储中 (在 React Native Web 中则存储于 `localStorage`) ，更新 provider 状态，加载该区域设置的翻译，并在不进行浏览器导航的情况下重新渲染。

对于公开页面，基于区域设置的 URL 可让每个语言版本可分享且可被搜索引擎索引。请在相应的特定于框架指南中配置路由：

* [Next.js App Router middleware](/docs/react/nextjs/app-router-middleware)
* [Next.js Pages Router locale routing](/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)。请改用 `generaltranslation` 中的 [`getLocaleProperties`](/docs/platform/core/reference/utility-functions/locales/get-locale-properties) 读取区域设置元数据。*

在 Next.js 中，这些钩子可用于同步的 App Router 服务器组件。在异步组件中，请调用 `gt-next/server` 提供的 [`getLocale`](/docs/react/nextjs/reference/functions/get-locale) 和 [`getLocaleDirection`](/docs/react/nextjs/reference/functions/get-locale-direction)：

```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

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.