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

title: requiresTranslation
description: Check whether translation is needed between two locales without a GT instance. API reference for requiresTranslation.

---

[`requiresTranslation`](/docs/platform/core/reference/gt-class-methods/locales/requires-translation) is a standalone utility function from General Translation's Core library that determines whether translation is needed between a source and a target locale.

## Overview [#overview]

Import `requiresTranslation` directly from `generaltranslation` and call it with the source and target locales. It does not require an API key or a [GT](/docs/platform/core/reference/gt-class/constructor) instance. For the instance-based equivalent, use the [`requiresTranslation`](/docs/platform/core/reference/gt-class-methods/locales/requires-translation) method on a [`GT`](/docs/platform/core/reference/gt-class/constructor) instance instead.

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

console.log(requiresTranslation('en-US', 'es-ES')); // true
console.log(requiresTranslation('en-US', 'en')); // false (same dialect)
```

Signature:

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

## How it works [#how-it-works]

Translation resolution follows these rules:

* If no target locale is specified, returns `false` (no translation needed).
* If the source and target locales are the same, returns `false`.
* If `approvedLocales` is provided and the target locale is not in that list, returns `false`.
* Otherwise, returns `true`.

Locales are compared with dialect awareness: only locales that resolve to the same dialect skip translation. `en-US` → `en` (same dialect) does not require translation, but `en-US` → `en-GB` does, because their regions differ. Any [`customMapping`](/docs/platform/core/reference/types/custom-mapping) is applied during comparison.

## Parameters [#parameters]

| Parameter                              | Description                                | Type                                                                  | Optional | Default |
| -------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------- | -------- | ------- |
| [`sourceLocale`](#source-locale)       | The locale of the original content.        | `string`                                                              | No       | —       |
| [`targetLocale`](#target-locale)       | The locale to translate the content into.  | `string`                                                              | No       | —       |
| [`approvedLocales`](#approved-locales) | Optional list of approved target locales.  | `string[]`                                                            | Yes      | —       |
| [`customMapping`](#custom-mapping)     | Custom mapping to apply during comparison. | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | Yes      | —       |

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

**Type** `string` · **Required**

The BCP-47 locale code of the original content.

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

**Type** `string` · **Required**

The BCP-47 locale code to translate the content into.

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

**Type** `string[]` · **Optional**

An optional list of approved target locales. If provided, any target locale not in the list returns `false`.

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

**Type** [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) · **Optional**

A custom mapping applied during locale comparison.

## Returns [#returns]

**Type** `boolean`

`true` if translation is required, `false` otherwise.

## Examples [#examples]

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

// Different languages require translation
console.log(requiresTranslation('en-US', 'es-ES')); // true
console.log(requiresTranslation('en-US', 'fr-FR')); // true

// Same dialect does not require translation
console.log(requiresTranslation('en-US', 'en-US')); // false
console.log(requiresTranslation('en-US', 'en')); // false (same dialect)

// Different dialects of the same language still require translation
console.log(requiresTranslation('en-US', 'en-GB')); // true (regions differ)

// With an approved locales filter
const approved = ['en-US', 'es-ES', 'fr-FR'];
console.log(requiresTranslation('en-US', 'it-IT', approved)); // false (not approved)
console.log(requiresTranslation('en-US', 'es-ES', approved)); // true (approved and different)
```

## Notes [#notes]

* Respects approved locale constraints.
* Returns `false` when the target is not in the approved list.
* Considers custom locale mappings.