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

title: getLocaleName
description: 返回易于理解的区域设置名称。getLocaleName 的 API 参考。

---

使用 `Intl.DisplayNames` API，在 [GT](/docs/platform/core/reference/gt-class/constructor) 实例上获取某个区域设置代码的显示名称。General Translation 会为任何有效的 BCP-47 区域设置代码返回易于理解的名称，并根据该实例的 source 区域设置进行本地化。

## 概览 [#overview]

在 [`GT`](/docs/platform/core/reference/gt-class/constructor) 实例上调用 `getLocaleName`，可选择传入区域设置代码。若省略，则会使用该实例的 `targetLocale`。

```typescript
const gt = new GT({ sourceLocale: 'en', targetLocale: 'es' });

const name = gt.getLocaleName('fr-CA');
console.log(name); // "加拿大法语"
```

签名：

```typescript
getLocaleName(locale?: string): string
```

*注意：`getLocaleName` 基于 `Intl.DisplayNames` 在本地运行，无需 API 密钥。省略 `locale` 时，它会使用该实例的 `targetLocale`。如果要在没有 `GT` 实例的情况下进行查找，请参阅独立的 [`getLocaleName`](/docs/platform/core/reference/utility-functions/locales/get-locale-name)。*

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

### 显示语言

显示名称会按以下规则进行本地化：

1. 实例的 `sourceLocale` (如果已配置) 。
2. 库的默认区域设置 (`'en'`) 。

### 自定义映射集成

* 系统会优先检查自定义区域设置映射。
* 如果定义了自定义名称，则以其为准。
* 否则会回退到 `Intl.DisplayNames` 来处理标准 BCP-47 代码。

### 缺少区域设置

如果未提供区域设置，且该实例未配置 `targetLocale`，则会抛出 `Error`。如果针对有效的区域设置未找到对应名称，则返回空字符串。

## 参数 [#parameters]

| 参数                  | 描述                       | 类型       | 可选 | 默认值                 |
| ------------------- | ------------------------ | -------- | -- | ------------------- |
| [`locale`](#locale) | 用于获取显示名称的 BCP-47 区域设置代码。 | `string` | 是  | `this.targetLocale` |

### `locale` [#locale]

**类型** `string` · **可选** · **默认值** `this.targetLocale`

要获取其显示名称的 BCP-47 区域设置代码。若未提供，则使用该实例的 `targetLocale`。

## 返回值 [#returns]

**类型** `string`

该区域设置的本地化显示名称。如果未提供区域设置，且该实例也未配置 `targetLocale`，则会抛出 `Error`。

## 示例 [#examples]

```typescript
const gt = new GT({ sourceLocale: 'en', targetLocale: 'fr' });

// 获取目标区域设置的名称
console.log(gt.getLocaleName()); // "French"

// 获取其他区域设置的名称
console.log(gt.getLocaleName('es')); // "Spanish"
console.log(gt.getLocaleName('de')); // "German"
console.log(gt.getLocaleName('ja')); // "Japanese"
```

## 备注 [#notes]

* 该方法使用实例的 `sourceLocale` 来确定显示语言。
* 自定义映射名称会优先于标准 `Intl.DisplayNames` 生效。