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

title: useLocaleProperties
description: 使用 General Translation gt-react 读取区域设置的显示元数据。useLocaleProperties 的 API 参考。

---

`useLocaleProperties` 钩子会返回某个区域设置的显示元数据——包括其名称、本地名称、语言、区域和书写系统。

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

*注意：`gt-tanstack-start` 不会导出此项。*

## 概览 [#overview]

使用区域设置代码调用 `useLocaleProperties`，即可获取其属性。

```tsx
import { useLocale, useLocaleProperties } from 'gt-react';

export default function LocaleInfo() {
  const locale = useLocale();
  const props = useLocaleProperties(locale); // [!code highlight]
  return (
    <div>
      <p>Name: {props.name}</p>
      <p>Native name: {props.nativeName}</p>
      <p>Region: {props.regionName}</p>
    </div>
  );
}
```

*注意：在 `gt-react` 中，请在 [`<GTProvider>`](/docs/react/reference/components/gt-provider) 内调用 `useLocaleProperties`。在 `gt-next` 中，它也可用于服务器组件。*

## 工作原理 [#how-it-works]

该钩子会将给定的区域设置代码解析为一个 [`LocaleProperties`](/docs/platform/core/reference/types/locale-properties) 对象，可用于构建自定义区域设置选择器，或向用户显示区域设置元数据。

## 参数 [#parameters]

| 参数                  | 描述       | 类型       | 可选 | 默认值 |
| ------------------- | -------- | -------- | -- | --- |
| [`locale`](#locale) | 要描述的区域设置 | `string` | 否  | —   |

### `locale` [#locale]

**类型** `string` · **必填**

BCP 47 区域设置代码，例如 `en-US` 或 `ja`。

## 返回值 [#returns]

**类型** [`LocaleProperties`](/docs/platform/core/reference/types/locale-properties)

一个描述区域设置的对象。主要字段包括：

| 字段                         | 描述                               | 类型       |
| -------------------------- | -------------------------------- | -------- |
| `code`                     | 区域设置代码，例如 `en-US`。               | `string` |
| `name`                     | 区域设置的英文名称，例如 `American English`。 | `string` |
| `nativeName`               | 该区域设置在其自身语言中的名称。                 | `string` |
| `languageCode`             | 语言子标签，例如 `en`。                   | `string` |
| `languageName`             | 语言的英文名称。                         | `string` |
| `nativeLanguageName`       | 该语言在其自身语言中的名称。                   | `string` |
| `nameWithRegionCode`       | 包含地区信息的区域设置名称，例如 `English (US)`。 | `string` |
| `nativeNameWithRegionCode` | 包含地区信息的本地区域设置名称。                 | `string` |
| `regionCode`               | 地区子标签，例如 `US`。                   | `string` |
| `regionName`               | 地区的英文名称。                         | `string` |
| `nativeRegionName`         | 该地区在该区域设置自身语言中的名称。               | `string` |
| `scriptCode`               | 书写系统子标签，例如 `Latn`。               | `string` |
| `scriptName`               | 书写系统的英文名称。                       | `string` |
| `nativeScriptName`         | 书写系统在其自身语言中的名称。                  | `string` |
| `maximizedCode`            | 完全展开的区域设置代码，例如 `en-Latn-US`。     | `string` |
| `emoji`                    | 与该区域设置所属地区关联的 Emoji。             | `string` |

完整字段列表请参阅 [`LocaleProperties`](/docs/platform/core/reference/types/locale-properties)。

## 注意 [#notes]

* `useLocaleProperties` 是同步的，可在服务器组件和客户端组件中使用。
* 要读取当前生效的区域设置，请使用 [`useLocale`](/docs/react/reference/hooks/use-locale)。