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

## 概述

独立的 `getLocaleName` 函数无需 GT 类实例即可获取区域设置代码的显示名称。
它使用 `Intl.DisplayNames` API，为任何有效的 BCP-47 区域设置代码提供本地化显示名称。

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

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

***


## 参考文档

### 参数

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

### 参数说明

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

### 返回值

`string` - 该区域设置的本地化显示名称。

***

## 行为

### 显示语言的确定顺序

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

1. `defaultLocale` 参数 (如果已提供) 
2. 库的默认区域设置 (&#39;en&#39;)

### 自定义映射集成

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

### 名称解析策略

1. **自定义映射名称** (最高优先级) 
2. 默认区域设置中的 **Intl.DisplayNames**
3. 库默认区域设置 (`en`) 中的 **Intl.DisplayNames**
4. **区域设置代码本身** (作为回退) 

***

## 示例

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

// 英文显示名称
console.log(getLocaleName('es', 'en')); // "Spanish (Spain)"
console.log(getLocaleName('ja', 'en')); // "Japanese (Japan)"
console.log(getLocaleName('zh', 'en')); // "Chinese (China)"
```


### 构建区域设置选项

```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 (United States)', emoji: '🇺🇸' },
//   { value: 'es', label: 'Spanish (Spain)', emoji: '🇪🇸' },
//   ...
// ]
```

***


## 说明

* 自定义映射的优先级高于标准 `Intl.DisplayNames`
* 如果无法确定显示名称，则返回区域设置代码本身
* 用于显示的区域设置参数决定返回名称所使用的语言

## 后续步骤

* 使用 [`getLocaleEmoji`](/docs/core/functions/locales/get-locale-emoji) 获取区域设置对应的 emoji
* 使用 GT 类方法 [`getLocaleName`](/docs/core/class/methods/locales/get-locale-name) 执行有状态操作
* 了解 [`CustomMapping` 类型](/docs/core/types/custom-mapping)