# generaltranslation: General Translation Core SDK: resolveCanonicalLocale
URL: https://generaltranslation.com/en-GB/docs/core/class/methods/locales/resolve-canonical-locale.mdx
---
title: resolveCanonicalLocale
description: API reference for the GT resolveCanonicalLocale method
---

## Overview

Used when aliasing locales (e.g. `cn` -> `zh`), the `resolveCanonicalLocale` method converts alias locale codes to their canonical BCP-47 locale codes when custom mapping is configured.

***

## Reference

### Parameters

<TypeTable
  type={{
  "locale?": {
    type: 'string',
    optional: true,
    default: 'this.targetLocale'
  },
  "customMapping?": {
    type: 'CustomMapping',
    optional: true,
    default: 'this.customMapping'
  }
}}
/>

### Parameter descriptions

| Parameter       | Description                                                                                                    |
| --------------- | -------------------------------------------------------------------------------------------------------------- |
| `locale`        | The alias locale code to resolve to canonical form. If not provided, the instance&#39;s `targetLocale` is used |
| `customMapping` | Optional custom mapping to use instead of the instance&#39;s mapping                                           |

### Returns

`string` - The canonical BCP-47 locale code if a mapping exists, otherwise the original locale code

### Throws

* `Error` - If no locale is provided and the instance has no `targetLocale` configured

***

## Examples

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

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

// Regular BCP-47 codes pass through unchanged
const unchanged = gt.resolveCanonicalLocale('fr-FR');
console.log(unchanged); // "fr-FR"
```

***


## Notes

* Converts alias locale codes to canonical BCP-47 locale codes
* Returns the original locale if no custom mapping exists
* Works with the `customMapping` configuration from the GT constructor
* No validation is performed on the input or output locale codes

## Next steps

* Resolve aliases with [`resolveAliasLocale`](/docs/core/class/methods/locales/resolve-alias-locale)
* Validate locales with [`isValidLocale`](/docs/core/class/methods/locales/is-valid-locale)
* Standardise locale format with [`standardizeLocale`](/docs/core/class/methods/locales/standardize-locale)