# General Translation React SDKs (gt-react, gt-next): useLocaleSelector
URL: https://generaltranslation.com/zh/docs/react/reference/hooks/use-locale-selector.mdx
---

title: useLocaleSelector
description: 使用 General Translation gt-react 构建自定义区域设置切换器。useLocaleSelector 的 API 参考。

---

`useLocaleSelector` 钩子会返回构建自定义区域设置切换器所需的状态：活动区域设置、可用区域设置、区域设置属性辅助工具，以及一个 setter。

*可在 `gt-react`、`gt-next`、`gt-tanstack-start` 和 `gt-react-native` 中使用。示例从 `gt-react` 导入；请改为从你所用框架对应的包中导入。*

## 概览 [#overview]

调用 `useLocaleSelector`，并将其返回值接入你自己的 `<select>` 或自定义 UI。

```tsx
'use client';
import { useLocaleSelector } from 'gt-react';

export default function MySelector() {
  const { locale, locales, setLocale, getLocaleProperties } = useLocaleSelector();

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

*注意：`useLocaleSelector` 仅可在客户端使用。如果你不需要自定义 UI，请改用 [`<LocaleSelector>`](/docs/react/reference/components/locale-selector) 组件。*

## 工作方式 [#how-it-works]

该钩子提供了选择器所需的全部内容：当前激活的 `locale`、`locales` 列表、用于切换区域设置的 `setLocale` (会保存你的选择并重新加载页面) ，以及用于渲染显示名称的 `getLocaleProperties`。传入部分 locales 即可限制可选项。

## 参数 [#parameters]

| 参数                    | 描述          | 类型         | 可选 | 默认值        |
| --------------------- | ----------- | ---------- | -- | ---------- |
| [`locales`](#locales) | 可提供的区域设置子集。 | `string[]` | 是  | 全部受支持的区域设置 |

### `locales` [#locales]

**类型** `string[]` · **可选** · **默认值** 所有受支持的区域设置

要提供的受支持区域设置子集。省略时，将使用 `<GTProvider>` 上下文中的区域设置。

## 返回值 [#returns]

**类型** `object`

| 字段                    | 说明              | 类型                                     |
| --------------------- | --------------- | -------------------------------------- |
| `locale`              | 当前选定的区域设置。      | `string`                               |
| `locales`             | 可用的区域设置。        | `string[]`                             |
| `setLocale`           | 更改当前生效的区域设置。    | `(locale: string) => void`             |
| `getLocaleProperties` | 获取某个区域设置的显示元数据。 | `(locale: string) => LocaleProperties` |

## 注意事项 [#notes]

* `useLocaleSelector` 仅限客户端使用。
* 如果需要现成的下拉列表，请使用 [`<LocaleSelector>`](/docs/react/reference/components/locale-selector)。