# generaltranslation: General Translation Core SDK: resolveCanonicalLocale
URL: https://generaltranslation.com/zh/docs/core/class/methods/locales/resolve-canonical-locale.mdx
---
title: resolveCanonicalLocale
description: GT resolveCanonicalLocale 方法的 API 参考文档
---

## 概述

`resolveCanonicalLocale` 方法用于别名区域设置场景 (例如 `cn` -> `zh`) 。配置了自定义映射时，它会将别名区域设置代码转换为其标准区域设置的 BCP-47 区域设置代码。

***

## 参考

### 参数

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

### 参数说明

| 参数              | 说明                                           |
| --------------- | -------------------------------------------- |
| `locale`        | 要解析为标准区域设置形式的别名区域设置代码。若未提供，则使用实例的 `targetLocale` |
| `customMapping` | 可选的自定义映射，将替代实例的映射                            |

### 返回值

`string` - 如果存在映射，则返回标准区域设置的 BCP-47 区域设置代码；否则返回原始的区域设置代码

### 抛出

* `Error` - 如果未提供区域设置，且该实例未配置 `targetLocale`，则会抛出此错误

***

## 示例

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

// 将别名转换为标准区域设置
const canonical = gt.resolveCanonicalLocale('cn');
console.log(canonical); // "zh"

// 常规 BCP-47 代码保持不变，直接传递
const unchanged = gt.resolveCanonicalLocale('fr-FR');
console.log(unchanged); // "fr-FR"
```

***


## 注意事项

* 将别名区域设置代码转换为标准区域设置的 BCP-47 区域设置代码
* 如果不存在自定义映射，则返回原始区域设置
* 使用 GT 构造函数中的 `customMapping` 设置
* 不会对输入或输出的区域设置代码执行任何校验

## 后续步骤

* 使用 [`resolveAliasLocale`](/docs/core/class/methods/locales/resolve-alias-locale) 解析回别名形式
* 使用 [`isValidLocale`](/docs/core/class/methods/locales/is-valid-locale) 验证区域设置
* 使用 [`standardizeLocale`](/docs/core/class/methods/locales/standardize-locale) 标准化区域设置格式