# generaltranslation: General Translation Core SDK: getLocaleProperties
URL: https://generaltranslation.com/zh/docs/core/functions/locales/get-locale-properties.mdx
---
title: getLocaleProperties
description: getLocaleProperties 独立函数的 API 参考
---

## 概述

独立的 `getLocaleProperties` 函数可在无需 GT 类实例的情况下获取某个区域设置代码的属性。
它会返回一个完整的 `LocaleProperties` 对象，其中包含显示名称、区域代码、书写系统信息以及旗帜表情等详细信息。

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

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

***


## 参考

### 参数

<TypeTable
  type={{
  "locale": {
    type: 'string',
    optional: false,
  },
  "defaultLocale?": {
    type: 'string',
    optional: true,
  },
  "customMapping?": {
    type: 'CustomMapping',
    optional: true,
  }
}}
/>

### 参数说明

| 参数              | 说明                           |
| --------------- | ---------------------------- |
| `locale`        | 用于获取属性的 BCP-47 区域设置代码        |
| `defaultLocale` | 用于本地化显示名称的区域设置 (默认为 `'en'`)  |
| `customMapping` | 区域设置代码和属性的可选自定义映射            |

### 返回值

`LocaleProperties` - 一个包含全部区域设置信息的完整对象：

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

***

## 行为

### 自定义映射集成

* 所有属性都会优先检查自定义映射
* 支持别名解析和属性覆盖
* 对未映射的代码回退到标准 `Intl` API
* 为别名区域设置解析出标准区域设置

***

## 示例

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

// 英语显示名称
const enProps = getLocaleProperties('es-MX', 'en');
console.log(enProps.name); // "Spanish (Mexico)"
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 (Mexique)"
console.log(frProps.languageName); // "espagnol"
console.log(frProps.regionName); // "Mexique"

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

***


## 注意事项

* 无需实例化 GT 类，该函数即可提供区域设置数据
* 自定义映射属性的优先级高于标准 Intl API
* 始终返回完整的 `LocaleProperties` 接口
* 原生名称始终基于目标区域设置本身计算

## 后续步骤

* 查看 [`LocaleProperties` 接口](/docs/core/types/locale-properties) - 完整的接口文档
* 使用 GT 类方法 [`getLocaleProperties`](/docs/core/class/methods/locales/get-locale-properties)
* 使用 [`getLocaleName`](/docs/core/functions/locales/get-locale-name) 获取简短的区域设置名称
* 使用 [`getLocaleEmoji`](/docs/core/functions/locales/get-locale-emoji) 获取区域设置对应的表情符号