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

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

---

Resolves a locale alias to the canonical BCP-47 locale code used internally, on a [GT](/docs/platform/core/reference/gt-class/constructor) instance. This is the inverse of [`resolveAliasLocale`](/docs/platform/core/reference/gt-class-methods/locales/resolve-alias-locale). General Translation uses a custom mapping so you can expose your own locale codes while translating and formatting against standard codes internally.

## Overview [#overview]

Call `resolveCanonicalLocale` on a [`GT`](/docs/platform/core/reference/gt-class/constructor) instance with a locale code. It returns the canonical locale when the code is a configured alias, or the input locale unchanged otherwise.

```typescript
const gt = new GT({
  sourceLocale: 'en',
  customMapping: {
    cn: { code: 'zh', name: 'Mandarin' },
  },
});

const canonical = gt.resolveCanonicalLocale('cn');
console.log(canonical); // "zh"
```

Signature:

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

*Note: `resolveCanonicalLocale` runs locally and does not require an API key. It uses the instance's target locale and `customMapping` when arguments are omitted. For resolution without a `GT` instance, see the standalone [`resolveCanonicalLocale`](/docs/platform/core/reference/utility-functions/locales/resolve-canonical-locale).*

## 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.
- **Instance fallback.** When `locale` is omitted, the instance's target locale is used; when `customMapping` is omitted, the instance's `customMapping` is used.
- **Throws** when no locale is available (neither an argument nor an instance target locale).

## Parameters [#parameters]

| Parameter | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| [`locale`](#locale) | The alias locale code to resolve to its canonical form. | `string` | Yes | `this.targetLocale` |
| [`customMapping`](#custom-mapping) | Custom mapping to use instead of the instance's mapping. | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | Yes | `this.customMapping` |

### `locale` [#locale]

**Type** `string` · **Optional** · **Default** `this.targetLocale`

The alias locale code to resolve. Falls back to the instance's target locale when omitted.

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

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

Custom mapping to use instead of the instance's mapping.

## Returns [#returns]

**Type** `string`

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

## Examples [#examples]

```typescript
const gt = new GT({
  sourceLocale: 'en',
  customMapping: {
    cn: { code: 'zh', name: 'Mandarin' },
  },
});

// Resolve alias to canonical locale
console.log(gt.resolveCanonicalLocale('cn')); // "zh"

// Non-mapped locale returns the original
console.log(gt.resolveCanonicalLocale('es')); // "es"
```

## Notes [#notes]

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