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

title: resolveCanonicalLocale
description: 在不需要 GT 实例的情况下，将区域设置别名解析为其规范区域设置代码。resolveCanonicalLocale 的 API 参考。

---

[`resolveCanonicalLocale`](/docs/platform/core/reference/gt-class-methods/locales/resolve-canonical-locale) 是 General Translation Core 库提供的一个独立实用函数，用于将区域设置别名解析为内部使用的规范 BCP-47 区域设置代码。它与 [`resolveAliasLocale`](/docs/platform/core/reference/gt-class-methods/locales/resolve-alias-locale) 的作用相反。

## 概览 [#overview]

直接从 `generaltranslation` 导入 `resolveCanonicalLocale`，并传入区域设置代码以及可选的自定义映射即可调用。它不需要 API key，也不需要 [`GT`](/docs/platform/core/reference/gt-class/constructor) 实例。如果要使用继承实例 mapping 的基于实例的解析方式，请改用 [`GT`](/docs/platform/core/reference/gt-class/constructor) 实例上的 [`resolveCanonicalLocale`](/docs/platform/core/reference/gt-class-methods/locales/resolve-canonical-locale) 方法。

```typescript
import { resolveCanonicalLocale } from 'generaltranslation';

const canonical = resolveCanonicalLocale('en', { en: { code: 'en-US' } });
// "en-US"
```

签名：

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

## 工作原理 [#how-it-works]

* **正向查找。** 在 [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) 中查找别名对应的规范区域设置。
* **透传。** 当输入的区域设置没有规范映射时，原样返回该区域设置。

## 参数 [#parameters]

| 参数                                 | 描述                  | 类型                                                                    | 可选 | 默认值 |
| ---------------------------------- | ------------------- | --------------------------------------------------------------------- | -- | --- |
| [`locale`](#locale)                | 要解析为其规范形式的别名区域设置代码。 | `string`                                                              | 否  | —   |
| [`customMapping`](#custom-mapping) | 用于解析规范区域设置的自定义映射。   | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | 是  | —   |

### `locale` [#locale]

**类型** `string` · **必填**

要解析的别名区域设置代码。

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

**类型** [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) · **可选**

用于解析规范区域设置的自定义映射。

## 返回值 [#returns]

**类型** `string`

别名 对应的规范区域设置；如果不存在规范映射，则保持输入的区域设置不变。

## 示例 [#examples]

```typescript
import { resolveCanonicalLocale } from 'generaltranslation';

// 无映射 — 原样返回输入值
console.log(resolveCanonicalLocale('en-US')); // "en-US"

// 使用 自定义映射 — 解析 别名
console.log(resolveCanonicalLocale('en', { en: { code: 'en-US' } })); // "en-US"
```

## 说明 [#notes]

* 这是 [`resolveAliasLocale`](/docs/platform/core/reference/utility-functions/locales/resolve-alias-locale) 的逆操作。
* 如果未找到规范映射，则会原样返回输入的区域设置。