# General Translation Platform: resolveCanonicalLocale
URL: https://generaltranslation.com/en-GB/docs/platform/core/reference/utility-functions/locales/resolve-canonical-locale.mdx
Docs index: https://generaltranslation.com/llms.txt
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 for the 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 if 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.

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.