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

title: resolveCanonicalLocale
description: 将 GT 实例上的区域设置别名解析为其规范区域设置代码。resolveCanonicalLocale 的 API 参考。

---

在 [GT](/docs/platform/core/reference/gt-class/constructor) 实例上，将区域设置别名解析为内部使用的规范 BCP-47 区域设置代码。这与 [`resolveAliasLocale`](/docs/platform/core/reference/gt-class-methods/locales/resolve-alias-locale) 的作用相反。General Translation 使用自定义映射，因此你既可以对外公开自己的区域设置代码，又能在内部基于标准代码进行翻译和格式化。

## 概览 [#overview]

在 [`GT`](/docs/platform/core/reference/gt-class/constructor) 实例上调用 `resolveCanonicalLocale`，并传入一个区域设置代码。如果该代码是已配置的 别名，它会返回对应的规范区域设置；否则会原样返回输入的区域设置。

```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]

**Type** `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) 的反向操作。
* 如果找不到规范映射，则会原样返回输入的区域设置。