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

title: LocaleSelector
description: 使用 General Translation gt-react 渲染一个用于切换当前区域设置的下拉菜单。LocaleSelector 的 API 参考。

---

`<LocaleSelector>` 组件会渲染一个下拉菜单，让用户可以切换当前区域设置。它是一个客户端组件。

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

*注意：`gt-react-native` 不导出此组件。若要使用自定义选择器，请使用 [`useLocaleSelector`](/docs/react/reference/hooks/use-locale-selector)。*

## 概览 [#overview]

可以在任意客户端组件中渲染 `<LocaleSelector>`。不传入任何属性时，它会列出已配置的 locales。

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

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

*注意：`<LocaleSelector>` 仅支持客户端。若需完全自定义的切换器，请使用 [`useLocaleSelector`](/docs/react/reference/hooks/use-locale-selector) 钩子。*

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

* **读取上下文。** 默认情况下，这些选项来自 `<GTProvider>` 上下文中的受支持 locales。传入 `locales` 可只显示其中一部分。
* **切换 locales。** 选择某个选项会设置当前活动 locales，并保存该选择后重新加载页面。
* **为空时不渲染任何内容。** 当没有可用的 locales 时，该组件会返回 `null`。

## 属性 [#props]

| 属性                                 | 描述                 | 类型         | 可选 | 默认         |
| ---------------------------------- | ------------------ | ---------- | -- | ---------- |
| [`locales`](#locales)              | 要显示的 locales 子集。        | `string[]` | 是  | 所有受支持的 locales |
| [`customMapping`](#custom-mapping) | 为 locales 自定义显示名称或属性映射。 | `object`   | 是  | —          |

### `locales` [#locales]

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

用于填充下拉菜单的区域设置代码子集，例如 `['en', 'es-MX', 'fr']`。如果省略，则使用 `<GTProvider>` 上下文中的 locales。

### `customMapping` [#custom-mapping]

**类型** `object` · **可选**

用于将区域设置代码映射到自定义显示名称、表情符号或其他属性。*注意：旧版 `customNames` prop (仅用于代码到名称的简单映射) 已弃用，建议改用 `customMapping`。*

## 示例 [#examples]

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

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

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

export default function MyComponent() {
  const customMapping = {
    en: 'English',
    es: 'Español',
    'fr-CA': 'Français (Canada)',
  };
  return <LocaleSelector customMapping={customMapping} />;
}
```

## 说明 [#notes]

* `<LocaleSelector>` 仅可在客户端使用。
* 要读取当前生效的区域设置，请使用 [`useLocale`](/docs/react/reference/hooks/use-locale)；要构建自定义选择器，请使用 [`useLocaleSelector`](/docs/react/reference/hooks/use-locale-selector)。