# General Translation Platform: requiresTranslation
URL: https://generaltranslation.com/en-US/docs/platform/core/reference/utility-functions/locales/requires-translation.mdx
Docs index: https://generaltranslation.com/llms.txt
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 the source, target, or any approved locale is invalid, returns `false`.
- If the source and target locales are the same, returns `false`.
- If `approvedLocales` is provided and does not contain the target language, 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. Matching uses the language, not the exact dialect. When provided, a target locale whose language is not represented 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)
console.log(requiresTranslation('en-US', 'es-MX', approved)); // true (Spanish is approved)
```

## Notes [#notes]

- Respects approved locale constraints.
- Matches approved locales by language, not exact dialect.
- Returns `false` when the target language is not represented in the approved list.
- Considers custom locale mappings.

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.