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

title: getLocaleName
description: Return a human-readable locale name without a GT instance. API reference for getLocaleName.

---

[`getLocaleName`](/docs/platform/core/reference/gt-class-methods/locales/get-locale-name) is a standalone utility function from General Translation's Core library that returns the display name of a locale code. It uses the `Intl.DisplayNames` API to produce a localized name for any valid BCP-47 locale code.

## Overview [#overview]

Import `getLocaleName` directly from `generaltranslation` and call it with a locale code and an optional display locale. It does not require an API key or a [GT](/docs/platform/core/reference/gt-class/constructor) instance. For the instance-based equivalent, use the [`getLocaleName`](/docs/platform/core/reference/gt-class-methods/locales/get-locale-name) method on a [`GT`](/docs/platform/core/reference/gt-class/constructor) instance instead.

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

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

Signature:

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

## How it works [#how-it-works]

### Display language resolution

The function localizes names using this priority:

1. The `defaultLocale` parameter, if provided.
2. The library default locale, `en`.

### Custom mapping integration

- Custom mappings are checked first for both locale codes and names.
- Supports alias resolution and custom display names.
- Falls back to standard `Intl.DisplayNames` for unmapped codes.

### Name resolution strategy

1. **Custom mapping name** (highest priority).
2. **`Intl.DisplayNames`** in the default locale.
3. **`Intl.DisplayNames`** in the library default (`en`).
4. **An empty string** (fallback).

*Note: the display name uses the CLDR dialect form, so `fr-CA` resolves to "Canadian French" and `es-ES` to "European Spanish" — not "French (Canada)" or "Spanish (Spain)". A base language such as `es` resolves to "Spanish", with no region.*

## Parameters [#parameters]

| Parameter | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| [`locale`](#locale) | BCP-47 locale code to get the display name for. | `string` | No | — |
| [`defaultLocale`](#default-locale) | Locale used to localize the display name. | `string` | Yes | `en` |
| [`customMapping`](#custom-mapping) | Custom mapping for locale codes and names. | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | Yes | — |

### `locale` [#locale]

**Type** `string` · **Required**

The BCP-47 locale code to get the display name for.

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

**Type** `string` · **Optional** · **Default** `en`

The locale used to localize the returned display name.

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

**Type** [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) · **Optional**

An optional custom mapping for locale codes and names.

## Returns [#returns]

**Type** `string`

The localized display name of the locale. Returns an empty string if no display name can be determined.

## Examples [#examples]

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

// English display names
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';

// Building locale options for a picker
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 [#notes]

- Custom mappings take precedence over standard `Intl.DisplayNames`.
- Returns an empty string if no display name can be determined.
- The `defaultLocale` parameter determines the language of the returned name.