# General Translation Platform: getLocaleProperties
URL: https://generaltranslation.com/zh/docs/platform/core/reference/utility-functions/locales/get-locale-properties.mdx
---

title: getLocaleProperties
description: 无需 GT 实例即可返回详细的区域设置属性。getLocaleProperties 的 API 参考。

---

[`getLocaleProperties`](/docs/platform/core/reference/gt-class-methods/locales/get-locale-properties) 是 General Translation 核心库提供的一个独立实用函数，用于返回某个区域设置代码的详细属性，包括显示名称、语言、书写系统和地区信息，以及一个具有代表性的 emoji。

## 概览 [#overview]

直接从 `generaltranslation` 导入 `getLocaleProperties`，并传入区域设置代码和可选的显示区域设置来调用它。它不需要 API 密钥，也不需要 [`GT`](/docs/platform/core/reference/gt-class/constructor) 实例。若要使用基于实例的对应方式，请改为调用 [`GT`](/docs/platform/core/reference/gt-class/constructor) 实例上的 [`getLocaleProperties`](/docs/platform/core/reference/gt-class-methods/locales/get-locale-properties) 方法。

```typescript
import { getLocaleProperties } from 'generaltranslation';

const props = getLocaleProperties('fr-CA', 'en');
console.log(props.name); // "Canadian French"
console.log(props.nativeName); // "français canadien"
console.log(props.emoji); // "🇨🇦"
console.log(props.regionCode); // "CA"
```

签名：

```typescript
getLocaleProperties(
  locale: string,
  defaultLocale?: string,
  customMapping?: CustomMapping
): LocaleProperties
```

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

* **完整元数据。** 返回完整的 [`LocaleProperties`](/docs/platform/core/reference/types/locale-properties) 对象，包括标准形式和最大化形式。
* **原生名称。** 无论 `defaultLocale` 是什么，原生名称始终都基于目标区域设置本身计算。
* **自定义映射集成。** 对所有属性，系统都会优先检查自定义映射，支持别名解析和属性覆盖；对于未映射的代码，则回退到标准 `Intl` API。带别名的区域设置会被解析为其规范区域设置。

*注意：显示名称使用 CLDR 的方言形式。例如，`getLocaleProperties('es-MX', 'en').name` 是 "Mexican Spanish" (而不是 "Spanish (Mexico)") ，而 `nativeName` 是 "español de México"。*

## 参数 [#parameters]

| 参数                                 | 描述                     | 类型                                                                    | 可选 | 默认值  |
| ---------------------------------- | ---------------------- | --------------------------------------------------------------------- | -- | ---- |
| [`locale`](#locale)                | 要获取其属性的 BCP-47 区域设置代码。 | `string`                                                              | 否  | —    |
| [`defaultLocale`](#default-locale) | 用于本地化显示名称的区域设置。        | `string`                                                              | 是  | `en` |
| [`customMapping`](#custom-mapping) | 用于区域设置代码和属性的自定义映射配置。   | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | 是  | —    |

### `locale` [#locale]

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

要获取其属性的 BCP-47 区域设置代码。

### `defaultLocale` [#default-locale]

**类型** `string` · **可选** · **默认值** `en`

用于本地化返回的显示名称所使用的区域设置。

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

**类型** [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) · **可选**

用于区域设置代码及其属性的自定义映射，可选。

## 返回值 [#returns]

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

一个包含所有区域设置信息的完整对象：

* `code`：标准化的区域设置代码。
* `name`：在默认区域设置下的显示名称。
* `nativeName`：在该区域设置自身中的显示名称。
* `languageCode`、`languageName`、`nativeLanguageName`：语言信息。
* `regionCode`、`regionName`、`nativeRegionName`：地区信息。
* `scriptCode`、`scriptName`、`nativeScriptName`：书写系统信息。
* `maximizedCode`、`minimizedCode`：规范化形式。
* `nameWithRegionCode`、`nativeNameWithRegionCode`：组合显示格式。
* `emoji`：旗帜或具有代表性的 emoji。

## 示例 [#examples]

```typescript
import { getLocaleProperties } from 'generaltranslation';

// 英语显示名称
const enProps = getLocaleProperties('es-MX', 'en');
console.log(enProps.name); // "Mexican Spanish"
console.log(enProps.languageName); // "Spanish"
console.log(enProps.regionName); // "Mexico"
console.log(enProps.emoji); // "🇲🇽"

// 法语显示名称
const frProps = getLocaleProperties('es-MX', 'fr');
console.log(frProps.name); // "espagnol du Mexique"
console.log(frProps.languageName); // "espagnol"
console.log(frProps.regionName); // "Mexique"

// 原生名称始终以目标区域设置的语言显示
console.log(enProps.nativeName); // "español de México"
console.log(frProps.nativeName); // "español de México"
```

## 注意事项 [#notes]

* 无需实例化 GT 类即可获取区域设置数据。
* 自定义映射属性的优先级高于标准 `Intl` API。
* 始终返回完整的 `LocaleProperties` 对象。
* 原生名称始终使用目标区域设置本身来计算。