# General Translation Platform: resolveCanonicalLocale
URL: https://generaltranslation.com/en-US/docs/platform/core/reference/utility-functions/locales/resolve-canonical-locale.mdx
---

title: resolveCanonicalLocale
description: Resolve a locale alias to its canonical locale code without a GT instance. API reference for resolveCanonicalLocale.

---

[`resolveCanonicalLocale`](/docs/platform/core/reference/gt-class-methods/locales/resolve-canonical-locale) is a standalone utility function from General Translation's Core library that resolves a locale alias to the canonical BCP-47 locale code used internally. It is the inverse of [`resolveAliasLocale`](/docs/platform/core/reference/gt-class-methods/locales/resolve-alias-locale).

## Overview [#overview]

Import `resolveCanonicalLocale` directly from `generaltranslation` and call it with a locale code and an optional custom mapping. It does not require an API key or a [GT](/docs/platform/core/reference/gt-class/constructor) instance. For instance-based resolution that inherits the instance mapping, use the [`resolveCanonicalLocale`](/docs/platform/core/reference/gt-class-methods/locales/resolve-canonical-locale) method on a [`GT`](/docs/platform/core/reference/gt-class/constructor) instance instead.

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

const canonical = resolveCanonicalLocale('en', { en: { code: 'en-US' } });
// "en-US"
```

Signature:

```typescript
resolveCanonicalLocale(
  locale: string,
  customMapping?: CustomMapping
): string
```

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

- **Forward lookup.** Looks up the canonical locale for an alias in the [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping).
- **Passthrough.** Returns the input locale unchanged when it has no canonical mapping.

## Parameters [#parameters]

| Parameter | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| [`locale`](#locale) | The alias locale code to resolve to its canonical form. | `string` | No | — |
| [`customMapping`](#custom-mapping) | Custom mapping used to resolve the canonical locale. | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | Yes | — |

### `locale` [#locale]

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

The alias locale code to resolve.

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

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

Custom mapping used to resolve the canonical locale.

## Returns [#returns]

**Type** `string`

The canonical locale for the alias, or the input locale unchanged when no canonical mapping exists.

## Examples [#examples]

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

// No mapping — returns the input unchanged
console.log(resolveCanonicalLocale('en-US')); // "en-US"

// With a custom mapping — resolves the alias
console.log(resolveCanonicalLocale('en', { en: { code: 'en-US' } })); // "en-US"
```

## Notes [#notes]

- This is the inverse of [`resolveAliasLocale`](/docs/platform/core/reference/utility-functions/locales/resolve-alias-locale).
- Returns the input locale unchanged if no canonical mapping is found.