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

title: requiresTranslation
description: Vérifie si une traduction est nécessaire entre deux paramètres régionaux sans instance GT. Référence de l’API pour requiresTranslation.

---

[`requiresTranslation`](/docs/platform/core/reference/gt-class-methods/locales/requires-translation) est une fonction utilitaire autonome de la bibliothèque principale de General Translation qui détermine si une traduction est nécessaire entre un paramètre régional source et un paramètre régional cible.

## Vue d’ensemble [#overview]

Importez `requiresTranslation` directement depuis `generaltranslation` et appelez-le avec les paramètres régionaux source et cible. Il ne nécessite ni clé API ni instance [GT](/docs/platform/core/reference/gt-class/constructor). Pour l’équivalent basé sur une instance, utilisez plutôt la méthode [`requiresTranslation`](/docs/platform/core/reference/gt-class-methods/locales/requires-translation) d’une instance [`GT`](/docs/platform/core/reference/gt-class/constructor).

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

console.log(requiresTranslation('en-US', 'es-ES')); // true
console.log(requiresTranslation('en-US', 'en')); // false (même dialecte)
```

Signature :

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

## Fonctionnement [#how-it-works]

La résolution de la traduction suit les règles suivantes :

* Si aucun paramètre régional cible n’est spécifié, renvoie `false` (aucune traduction nécessaire).
* Si le paramètre régional source et le paramètre régional cible sont identiques, renvoie `false`.
* Si `approvedLocales` est fourni et que le paramètre régional cible ne figure pas dans cette liste, renvoie `false`.
* Sinon, renvoie `true`.

Les locales sont comparées en tenant compte des variantes dialectales : seules celles qui correspondent au même dialecte n’entraînent pas de traduction. `en-US` → `en` (même dialecte) ne nécessite pas de traduction, mais `en-US` → `en-GB`, si, car leurs régions diffèrent. Tout [`customMapping`](/docs/platform/core/reference/types/custom-mapping) est appliqué lors de la comparaison.

## Paramètres [#parameters]

| Paramètre                              | Description                                                  | Type                                                                  | Facultatif | Par défaut |
| -------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------- | ---------- | ---------- |
| [`sourceLocale`](#source-locale)       | Le paramètre régional du contenu source.                     | `string`                                                              | Non        | —          |
| [`targetLocale`](#target-locale)       | Le paramètre régional dans lequel traduire le contenu.       | `string`                                                              | Non        | —          |
| [`approvedLocales`](#approved-locales) | Liste facultative des paramètres régionaux cibles approuvés. | `string[]`                                                            | Oui        | —          |
| [`customMapping`](#custom-mapping)     | Mappage personnalisé à appliquer lors de la comparaison.     | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | Oui        | —          |

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

**Type** `string` · **Obligatoire**

Le code de langue BCP-47 du contenu original.

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

**Type** `string` · **Obligatoire**

Le code de langue BCP-47 dans lequel traduire le contenu.

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

**Type** `string[]` · **Facultatif**

Liste facultative des paramètres régionaux cibles autorisés. Lorsqu’elle est fournie, un paramètre régional cible qui ne figure pas dans cette liste renvoie `false`.

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

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

Un mapping personnalisé appliqué lors de la comparaison des paramètres régionaux.

## Retourne [#returns]

**Type** `boolean`

`true` si une traduction est nécessaire, `false` sinon.

## Exemples [#examples]

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

// Les langues différentes nécessitent une traduction
console.log(requiresTranslation('en-US', 'es-ES')); // true
console.log(requiresTranslation('en-US', 'fr-FR')); // true

// Le même dialecte ne nécessite pas de traduction
console.log(requiresTranslation('en-US', 'en-US')); // false
console.log(requiresTranslation('en-US', 'en')); // false (même dialecte)

// Les dialectes différents d'une même langue nécessitent tout de même une traduction
console.log(requiresTranslation('en-US', 'en-GB')); // true (régions différentes)

// Avec un filtre de paramètres régionaux approuvés
const approved = ['en-US', 'es-ES', 'fr-FR'];
console.log(requiresTranslation('en-US', 'it-IT', approved)); // false (non approuvé)
console.log(requiresTranslation('en-US', 'es-ES', approved)); // true (approuvé et différent)
```

## Notes [#notes]

* Respecte les contraintes liées aux paramètres régionaux approuvés.
* Renvoie `false` lorsque le paramètre régional cible ne figure pas dans la liste approuvée.
* Tient compte des correspondances personnalisées de paramètres régionaux.