# General Translation Platform: resolveCanonicalLocale
URL: https://generaltranslation.com/ru/docs/platform/core/reference/gt-class-methods/locales/resolve-canonical-locale.mdx
---
title: resolveCanonicalLocale
description: Преобразует алиас локали в код её канонической локали на экземпляре GT. Справочник API для resolveCanonicalLocale.

---

Преобразует алиас локали в код канонической локали BCP-47, который экземпляр [GT](/docs/platform/core/reference/gt-class/constructor) использует внутри системы. Это операция, обратная [`resolveAliasLocale`](/docs/platform/core/reference/gt-class-methods/locales/resolve-alias-locale). General Translation использует пользовательское сопоставление, поэтому вы можете использовать собственные коды локалей, а для перевода и форматирования внутри системы применять стандартные коды.

## Обзор [#overview]

Вызовите `resolveCanonicalLocale` для экземпляра [`GT`](/docs/platform/core/reference/gt-class/constructor), передав код локали. Метод возвращает каноническую локаль, если код является настроенным алиасом; в противном случае входная локаль возвращается без изменений.

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

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

Сигнатура:

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

*Примечание: `resolveCanonicalLocale` выполняется локально и не требует API-ключа. Если аргументы опущены, используется целевая локаль экземпляра и `customMapping`. Чтобы выполнить определение без экземпляра `GT`, см. автономную функцию [`resolveCanonicalLocale`](/docs/platform/core/reference/utility-functions/locales/resolve-canonical-locale).*

## Как это работает [#how-it-works]

* **Прямой поиск.** Ищет каноническую локаль для алиаса в [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping).
* **Сквозная передача.** Возвращает входную локаль без изменений, если для неё нет канонического сопоставления.
* **Резервное значение экземпляра.** Если `locale` не указана, используется целевая локаль экземпляра; если `customMapping` не указан, используется `customMapping` экземпляра.
* **Выбрасывает ошибку**, если локаль недоступна (не передан ни аргумент, ни целевая локаль экземпляра).

## Параметры [#parameters]

| Параметр                           | Описание                                                                      | Тип                                                                   | Необязательно | По умолчанию         |
| ---------------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------- | -------------------- |
| [`locale`](#locale)                | Код локали-алиаса, который нужно преобразовать в каноническую форму.          | `string`                                                              | Да            | `this.targetLocale`  |
| [`customMapping`](#custom-mapping) | Пользовательское сопоставление, используемое вместо сопоставления экземпляра. | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | Да            | `this.customMapping` |

### `locale` [#locale]

**Тип** `string` · **Необязательный** · **По умолчанию** `this.targetLocale`

Код локали-алиаса, для которого нужно определить итоговую локаль. Если не указано, используется целевая локаль экземпляра.

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

**Тип** [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) · **Необязательно** · **По умолчанию** `this.customMapping`

Пользовательское сопоставление, используемое вместо сопоставления экземпляра.

## Возвращает [#returns]

**Тип** `string`

Каноническая локаль для алиаса или исходная локаль без изменений, если каноническое соответствие отсутствует.

## Примеры [#examples]

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

// Разрешить алиас в каноническую локаль
console.log(gt.resolveCanonicalLocale('cn')); // "zh"

// Локаль без маппинга возвращает исходное значение
console.log(gt.resolveCanonicalLocale('es')); // "es"
```

## Заметки [#notes]

* Это обратная операция к [`resolveAliasLocale`](/docs/platform/core/reference/gt-class-methods/locales/resolve-alias-locale).
* Возвращает исходную локаль без изменений, если каноническое сопоставление не найдено.