# gt-next: General Translation Next.js SDK: useLocaleProperties
URL: https://generaltranslation.com/zh/docs/next/api/helpers/use-locale-properties.mdx
---
title: useLocaleProperties
description: useLocaleProperties hook 的 API 参考文档
---

{/* 自动生成：请勿直接编辑。请改为编辑 content/docs-templates/ 中的模板。 */}


## 概述

`useLocaleProperties` Hook 会返回给定区域设置的元数据，包括其名称、原生名称、语言、地区和脚本信息。

<Callout>
  `useLocaleProperties` 是一个客户端 Hook，*只能在客户端组件中使用*。
  请确保你的应用已使用 [`<GTProvider>`](/docs/next/api/components/gtprovider) 包裹。
</Callout>

## 参考

### 参数

| 参数       | 类型       | 描述                                        |
| -------- | -------- | ----------------------------------------- |
| `locale` | `string` | 符合 BCP 47 的区域设置代码 (例如 `'en-US'`、`'ja'`) 。 |

### 返回值

一个 `LocaleProperties` 对象，包含以下字段：

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

***

## 示例

### 基本用法

```jsx title="LocaleInfo.jsx" copy
'use client';
import { useLocaleProperties } from 'gt-next';
import { useLocale } from 'gt-next';

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>
  );
}
```

***


## 注意

* 此 Hook 是同步的，会直接返回这些属性。
* 适合用于构建自定义区域设置选择器，或向用户显示区域设置元数据。

## 后续步骤

* 进一步了解[区域设置代码](/docs/core/locales)。