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

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

---

[`requiresTranslation`](/docs/platform/core/reference/gt-class-methods/locales/requires-translation) 是 General Translation Core 库提供的一个独立实用函数，用于判断源区域设置与目标区域设置之间是否需要翻译。

## 概览 [#overview]

直接从 `generaltranslation` 导入 `requiresTranslation`，并传入源区域设置和目标区域设置进行调用。它既不需要 API 密钥，也不需要 [GT](/docs/platform/core/reference/gt-class/constructor) 实例。若要使用基于实例的等效方式，请改用 [`GT`](/docs/platform/core/reference/gt-class/constructor) 实例上的 [`requiresTranslation`](/docs/platform/core/reference/gt-class-methods/locales/requires-translation) 方法。

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

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

签名：

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

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

翻译解析遵循以下规则：

* 如果未指定目标区域设置，则返回 `false` (无需翻译) 。
* 如果源区域设置与目标区域设置相同，则返回 `false`。
* 如果提供了 `approvedLocales`，且目标区域设置不在该列表中，则返回 `false`。
* 否则，返回 `true`。

比较区域设置时会识别方言：只有解析为同一方言的区域设置才会跳过翻译。`en-US` → `en` (同一方言) 无需翻译，但 `en-US` → `en-GB` 需要翻译，因为它们所属的区域不同。比较时还会应用任何 [`customMapping`](/docs/platform/core/reference/types/custom-mapping)。

## 参数 [#parameters]

| 参数                                     | 描述               | 类型                                                                    | 可选 | 默认值 |
| -------------------------------------- | ---------------- | --------------------------------------------------------------------- | -- | --- |
| [`sourceLocale`](#source-locale)       | 原始内容的区域设置。       | `string`                                                              | 否  | —   |
| [`targetLocale`](#target-locale)       | 要翻译成的目标区域设置。     | `string`                                                              | 否  | —   |
| [`approvedLocales`](#approved-locales) | 可选的已获批准目标区域设置列表。 | `string[]`                                                            | 是  | —   |
| [`customMapping`](#custom-mapping)     | 比较时应用的自定义映射。     | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | 是  | —   |

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

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

原始内容的 BCP-47 区域设置代码。

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

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

要将内容翻译为的 BCP-47 区域设置代码。

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

**类型** `string[]` · **可选**

可选的已批准目标区域设置列表。提供后，不在此列表中的目标区域设置将返回 `false`。

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

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

用于比较区域设置时的自定义映射。

## 返回值 [#returns]

**类型** `boolean`

如果需要翻译，则为 `true`；否则为 `false`。

## 示例 [#examples]

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

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

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

// 同一语言的不同方言仍需要翻译
console.log(requiresTranslation('en-US', 'en-GB')); // true（地区不同）

// 使用已批准的 locales 过滤器
const approved = ['en-US', 'es-ES', 'fr-FR'];
console.log(requiresTranslation('en-US', 'it-IT', approved)); // false（未批准）
console.log(requiresTranslation('en-US', 'es-ES', approved)); // true（已批准且不同）
```

## 注意事项 [#notes]

* 遵循 approved locale 的限制。
* 当目标不在批准列表中时，返回 `false`。
* 会考虑自定义区域设置映射。