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

title: getLocaleName
description: 返回无需 GT 实例即可获取的人类可读区域设置名称。getLocaleName 的 API 参考。

---

[`getLocaleName`](/docs/platform/core/reference/gt-class-methods/locales/get-locale-name) 是 General Translation Core library 提供的一个独立工具函数，用于返回区域设置代码的显示名称。它使用 `Intl.DisplayNames` API，为任何有效的 BCP-47 区域设置代码生成本地化名称。

## 概览 [#overview]

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

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

const name = getLocaleName('fr-CA', 'en');
console.log(name); // "Canadian French"
```

签名：

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

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

### 显示语言的确定方式

该函数会按以下优先级对名称进行本地化：

1. 如果提供了 `defaultLocale` 参数，则优先使用它。
2. 否则使用库的默认区域设置 `en`。

### 自定义映射集成

* 对区域设置代码和名称，系统会优先检查自定义映射。
* 支持别名解析和自定义显示名称。
* 对于未映射的代码，会回退到标准的 `Intl.DisplayNames`。

### 名称解析策略

1. **自定义映射名称** (最高优先级) 。
2. 默认区域设置中的 **`Intl.DisplayNames`**。
3. 库默认值 (`en`) 中的 **`Intl.DisplayNames`**。
4. **空字符串** (后备内容) 。

*注意：显示名称使用 CLDR 的方言形式，因此 `fr-CA` 会解析为“Canadian French”，`es-ES` 会解析为“European Spanish”——而不是“French (Canada)”或“Spanish (Spain)”。像 `es` 这样的基础语言会解析为“Spanish”，不带区域信息。*

## 参数 [#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]

**类型** `string`

该区域设置的本地化显示名称。如无法确定显示名称，则返回空字符串。

## 示例 [#examples]

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

// 英语显示名称
console.log(getLocaleName('es', 'en')); // "Spanish"
console.log(getLocaleName('ja', 'en')); // "Japanese"
console.log(getLocaleName('zh', 'en')); // "Chinese"
console.log(getLocaleName('fr-CA', 'en')); // "Canadian French"
console.log(getLocaleName('es-ES', 'en')); // "European Spanish"
```

```typescript
import { getLocaleName, getLocaleEmoji } from 'generaltranslation';

// 为选择器构建区域设置选项
function buildLocaleOptions(
  supportedLocales: string[],
  displayLocale: string = 'en'
) {
  return supportedLocales.map((locale) => ({
    value: locale,
    label: getLocaleName(locale, displayLocale),
    emoji: getLocaleEmoji(locale),
  }));
}

const options = buildLocaleOptions(['en', 'es', 'fr', 'de', 'ja'], 'en');

console.log(options);
// [
//   { value: 'en', label: 'English', emoji: '🇺🇸' },
//   { value: 'es', label: 'Spanish', emoji: '🇪🇸' },
//   ...
// ]
```

## 注意事项 [#notes]

* 自定义映射的优先级高于标准 `Intl.DisplayNames`。
* 如果无法确定显示名称，则返回空字符串。
* `defaultLocale` 参数决定返回名称的语言。