# General Translation Platform: requiresTranslation
URL: https://generaltranslation.com/zh/docs/platform/core/reference/gt-class-methods/locales/requires-translation.mdx
---

title: requiresTranslation
description: 检查两个区域设置之间是否需要翻译。requiresTranslation 的 API 参考。

---

判断在 [GT](/docs/platform/core/reference/gt-class/constructor) 实例中，源区域设置与目标区域设置之间是否需要翻译。General Translation 会比较区域设置代码，并结合已批准的区域设置列表，判断内容是否需要翻译。

## 概览 [#overview]

在 [`GT`](/docs/platform/core/reference/gt-class/constructor) 实例上调用 `requiresTranslation` 时，可以选择传入源区域设置和目标区域设置。若省略，则使用该实例的 `sourceLocale` 和 `targetLocale`。

```typescript
const gt = new GT({
  sourceLocale: 'en-US',
  targetLocale: 'es-ES',
  locales: ['en-US', 'es-ES', 'fr-FR', 'de-DE'],
});

console.log(gt.requiresTranslation('en-US', 'es-ES')); // true（需要翻译）
console.log(gt.requiresTranslation('en', 'en-US')); // false（相同方言）
```

签名：

```typescript
requiresTranslation(
  sourceLocale?: string,
  targetLocale?: string,
  approvedLocales?: string[],
  customMapping?: CustomMapping
): boolean
```

*注意：`requiresTranslation` 在本地运行，无需 API 密钥。省略参数时，它会使用该实例的 `sourceLocale`、`targetLocale`、`locales` 和 `customMapping`。如果要在没有 `GT` 实例的情况下进行检查，请参阅独立的 [`requiresTranslation`](/docs/platform/core/reference/utility-functions/locales/requires-translation)。*

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

该方法会按以下顺序判断：

1. **有效性。** 如果 source、target 或任一已批准的区域设置不是有效的区域设置，则返回 `false`。
2. **相同方言。** 如果 source 和 target 属于同一方言 (例如 `en` 和 `en-US`) ，则返回 `false`——无需翻译。
3. **无批准列表。** 如果没有适用的 `approvedLocales`，则只要 source 和 target 不同，就返回 `true`。
4. **批准范围。** 否则，只有当 target 的语言与至少一个已批准区域设置的语言一致时，才返回 `true`；同一语言的不同方言仍视为需要翻译 (因此更接近的方言可以作为后备内容) 。如果已批准的区域设置中不包含 target 所属的语言，则返回 `false`。

省略 `sourceLocale` 或 `targetLocale` 时，会使用该实例中的值。如果未提供源区域设置且实例没有 `sourceLocale`，或者未提供目标区域设置且实例没有 `targetLocale`，则会抛出 `Error`。

## 参数 [#parameters]

| 参数                                     | 描述              | 类型                                                                    | 可选 | 默认值                  |
| -------------------------------------- | --------------- | --------------------------------------------------------------------- | -- | -------------------- |
| [`sourceLocale`](#source-locale)       | 源区域设置代码。        | `string`                                                              | 是  | `this.sourceLocale`  |
| [`targetLocale`](#target-locale)       | 目标区域设置代码。       | `string`                                                              | 是  | `this.targetLocale`  |
| [`approvedLocales`](#approved-locales) | 已批准的目标区域设置数组。   | `string[]`                                                            | 是  | `this.locales`       |
| [`customMapping`](#custom-mapping)     | 用于解析区域设置的自定义映射。 | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | 是  | `this.customMapping` |

### `sourceLocale` [#source-locale]

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

源区域设置代码。若未提供，则使用该实例的 `sourceLocale`。

### `targetLocale` [#target-locale]

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

目标区域设置代码。若未提供，则使用该实例的 `targetLocale`。

### `approvedLocales` [#approved-locales]

**类型** `string[]` · **可选** · **默认值** `this.locales`

已批准的目标区域设置数组。若未提供，则使用该实例的 `locales` 数组。如果目标区域设置不在此列表中，该方法将返回 `false`。

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

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

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

## 返回值 [#returns]

**类型** `boolean`

如果需要翻译，则返回 `true`；否则返回 `false`。如果无法解析 source 或目标区域设置，则会抛出 `Error`。

## 示例 [#examples]

```typescript
const gt = new GT({
  sourceLocale: 'en-US',
  targetLocale: 'es-ES',
  locales: ['en-US', 'es-ES', 'fr-FR', 'de-DE'],
});

// 不同语言需要翻译
console.log(gt.requiresTranslation('en-US', 'es-ES')); // true
console.log(gt.requiresTranslation('en-US', 'fr-FR')); // true

// 完全相同的方言不需要翻译
console.log(gt.requiresTranslation('en-US', 'en-US')); // false
console.log(gt.requiresTranslation('es-ES', 'es-ES')); // false
console.log(gt.requiresTranslation('en', 'en-US')); // false（相同方言）

// 同一语言的不同方言需要翻译
// （更接近的方言可作为后备内容）
console.log(gt.requiresTranslation('en-US', 'en-GB')); // true
console.log(gt.requiresTranslation('es-ES', 'es-MX')); // true

// 目标语言不在已批准的区域设置中
console.log(gt.requiresTranslation('en-US', 'it-IT')); // false（it-IT 不在已批准的区域设置中）
```

## 说明 [#notes]

* 仅在以下情况下返回 `false`：方言完全相同、区域设置无效，或目标语言未包含在已批准的区域设置中。
* 同一种语言的不同方言 (例如 `en-US` 和 `en-GB`) 仍需要翻译，因此更接近的方言可以作为后备内容。
* 遵循已批准的区域设置列表：按语言匹配，而不是按精确方言匹配。