# General Translation Platform: isValidLocale
URL: https://generaltranslation.com/zh/docs/platform/core/reference/gt-class-methods/locales/is-valid-locale.mdx
---

title: isValidLocale
description: 检查某个值是否为有效的区域设置代码。isValidLocale 的 API 参考。

---

在 [GT](/docs/platform/core/reference/gt-class/constructor) 实例上，验证某个区域设置代码的格式是否正确，以及它是否会被识别为有效的 BCP-47 区域设置。General Translation 使用 `Intl` API 检查区域设置结构、语言识别以及地区/书写系统是否有效，并支持自定义区域设置映射。

## 概览 [#overview]

在 [`GT`](/docs/platform/core/reference/gt-class/constructor) 实例上调用 `isValidLocale` 时，可以选择传入一个区域设置代码。若省略，则会使用该实例的 `targetLocale`。

```typescript
const gt = new GT({ sourceLocale: 'en', targetLocale: 'es' });

console.log(gt.isValidLocale('en-US')); // true
console.log(gt.isValidLocale('invalid-locale')); // false
```

签名：

```typescript
isValidLocale(
  locale?: string,
  customMapping?: CustomMapping
): boolean
```

*注意：`isValidLocale` 会使用 `Intl` API 在本地运行，无需 API 密钥。省略这些参数时，它会使用该实例的 `targetLocale` 和 `customMapping`。如果要在没有 `GT` 实例的情况下进行验证，请参阅独立的 [`isValidLocale`](/docs/platform/core/reference/utility-functions/locales/is-valid-locale)。*

## 工作方式 [#how-it-works]

* **BCP-47 验证。** 使用浏览器的 `Intl` API 对 BCP-47 区域设置进行全面验证。
* **自定义映射解析。** 如果某个区域设置是 [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) 中的键，则会先将其解析为对应的规范 `code`，再通过标准的 `Intl` 检查进行验证——使用自定义映射的区域设置并不意味着它会自动有效。
* **私用代码。** 支持私用语言代码 (`qaa`–`qtz`) 。
* **区域设置回退。** 省略 `locale` 时，会使用实例的 `targetLocale`。
* **缺少区域设置。** 如果未提供区域设置，且实例也未配置 `targetLocale`，则会抛出 `Error`。

## 参数 [#parameters]

| 参数                                 | 描述                      | 类型                                                                    | 可选 | 默认值                  |
| ---------------------------------- | ----------------------- | --------------------------------------------------------------------- | -- | -------------------- |
| [`locale`](#locale)                | 要验证的 BCP-47 区域设置代码。     | `string`                                                              | 是  | `this.targetLocale`  |
| [`customMapping`](#custom-mapping) | 用于检查是否存在其他有效区域设置的自定义映射。 | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | 是  | `this.customMapping` |

### `locale` [#locale]

**类型** `string` · **可选** · **默认值** `this.targetLocale`

要验证的 BCP-47 区域设置代码。若未提供，则使用实例的 `targetLocale`。

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

**类型** [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) · **可选** · **默认值** `this.customMapping`

用于检查是否存在其他有效区域设置的自定义映射。若未提供，则使用该实例的 `customMapping`。

## 返回值 [#returns]

**类型** `boolean`

如果 `locale` 有效，则返回 `true`；否则返回 `false`。如果未提供区域设置，且该实例也未配置 `targetLocale`，则会抛出 `Error`。

## 示例 [#examples]

```typescript
const gt = new GT({ sourceLocale: 'en', targetLocale: 'es' });

const isValid = gt.isValidLocale('en-US');
console.log(isValid); // true

const isInvalid = gt.isValidLocale('invalid-locale');
console.log(isInvalid); // false
```

## 注意事项 [#notes]

* 使用浏览器的 `Intl` API 执行全面的 BCP-47 区域设置验证。
* 自定义映射的键会先解析为其规范 `code`，再通过标准的 `Intl` 检查进行验证 (它们并不会自动被视为有效) 。
* 支持私用语言代码 (`qaa`–`qtz`) 。
* 对于格式错误或无法识别的区域设置代码，返回 `false`。