# gt-node: General Translation Node.js SDK: Configuration
URL: https://generaltranslation.com/fr/docs/node/reference/config.mdx
---

title: Configuration
description: Configurez la bibliothèque `gt-node` de General Translation avec `initializeGT`. Référence API de la configuration de `gt-node`.

---

La bibliothèque `gt-node` se configure au moyen d’un seul appel à [`initializeGT`](/docs/node/reference/functions/initialize-gt) au démarrage. `gt-node` ne lit pas automatiquement `gt.config.json` ni les variables d’environnement : chaque valeur est lue à partir de l’objet que vous passez à `initializeGT`. Cette page documente les propriétés acceptées par cet appel.

## Vue d’ensemble [#overview]

Appelez `initializeGT` une seule fois, avant de traiter les requêtes, en lui passant un objet de configuration. Cette fonction est synchrone et ne renvoie rien.

```ts
import { initializeGT } from 'gt-node';

initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr'],
  projectId: process.env.GT_PROJECT_ID,
});
```

Les clés correspondent à celles que lit la [`gt` CLI](/docs/cli/quickstart) dans `gt.config.json`. Pour garder les deux synchronisés, importez votre `gt.config.json` et utilisez l’opérateur spread pour passer ses champs à l’appel :

```ts
import { initializeGT } from 'gt-node';
import gtConfig from './gt.config.json' with { type: 'json' };

initializeGT(gtConfig);
```

Le type de configuration est `InitializeGTParams`, qui correspond à la combinaison des options de résolution du paramètre régional et des options de cache de traduction.

## Options [#options]

| Option                                       | Description                                                                                                | Type                                                                  | Facultatif | Par défaut        |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ---------- | ----------------- |
| [`defaultLocale`](#default-locale)           | Paramètre régional source et de secours.                                                                   | `string`                                                              | Oui        | `'en'`            |
| [`locales`](#locales)                        | Paramètres régionaux cibles pris en charge.                                                                | `string[]`                                                            | Oui        | `[defaultLocale]` |
| [`projectId`](#project-id)                   | ID du projet ; active le loader CDN de General Translation lorsqu’il est défini.                           | `string`                                                              | Oui        | —                 |
| [`devApiKey`](#dev-api-key)                  | Clé API de développement pour la traduction à la demande.                                                  | `string`                                                              | Oui        | —                 |
| [`apiKey`](#api-key)                         | Clé API de production.                                                                                     | `string`                                                              | Oui        | —                 |
| [`cacheUrl`](#cache-url)                     | Hôte du cache de traduction. `null` désactive le chargement distant.                                       | `string \| null`                                                      | Oui        | GT CDN            |
| [`runtimeUrl`](#runtime-url)                 | Hôte de traduction à l’exécution. `null` le désactive.                                                     | `string \| null`                                                      | Oui        | GT runtime        |
| [`loadTranslations`](#load-translations)     | Loader personnalisé renvoyant des traductions pour un paramètre régional.                                  | `TranslationsLoader`                                                  | Oui        | —                 |
| [`customMapping`](#custom-mapping)           | Alias de paramètres régionaux et surcharges de propriétés.                                                 | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | Oui        | —                 |
| [`cacheExpiryTime`](#cache-expiry)           | Durée de vie du cache du paramètre régional, en millisecondes. `null` désactive l’expiration.              | `number \| null`                                                      | Oui        | —                 |
| [`dictionary`](#dictionary)                  | Dictionnaire de langue source lu par [`getTranslations`](/docs/node/reference/functions/get-translations). | `Dictionary`                                                          | Oui        | —                 |
| [`loadDictionary`](#load-dictionary)         | Loader renvoyant un dictionnaire pour un paramètre régional.                                               | `DictionaryLoader`                                                    | Oui        | —                 |
| [`runtimeTranslation`](#runtime-translation) | `timeout` et `metadata` de la traduction à l’exécution.                                                    | `object`                                                              | Oui        | `timeout` 12000   |
| [`batchConfig`](#batch-config)               | Limites de traitement par lots pour la traduction à l’exécution.                                           | `object`                                                              | Oui        | —                 |
| [`modelProvider`](#model-provider)           | Clé du fournisseur de modèle reprise depuis `gt.config.json`. Non utilisée par le runtime.                 | `string`                                                              | Oui        | —                 |

*Remarque : `initializeGT` accepte également des clés internes préfixées par un trait de soulignement (`_versionId`, `_branchId`, `_disableDevHotReload`), ainsi qu’un objet `files` utilisé par le compilateur CLI. Ces éléments ne font pas partie de la surface publique stable et sont donc omis ici.*

## `defaultLocale` [#default-locale]

**Type** `string` · **Facultatif** · **Par défaut** `'en'`

Le paramètre régional par défaut de votre application. Il s’agit du paramètre régional dans lequel votre contenu source est rédigé, ainsi que du paramètre régional de secours lorsqu’aucune traduction n’est trouvée. S’il est omis, la valeur par défaut est le paramètre régional par défaut de la bibliothèque, `'en'`.

```ts
initializeGT({ defaultLocale: 'en-US' });
```

## `locales` [#locales]

**Type** `string[]` · **Facultatif** · **Par défaut** `[defaultLocale]`

Un tableau de [codes de langue](/docs/platform/core/reference/utility-functions/locales/is-valid-locale) pris en charge par votre application. Le `defaultLocale` est toujours inclus dans l’ensemble des paramètres régionaux pris en charge, même si vous l’omettez ici.

```ts
initializeGT({ defaultLocale: 'en', locales: ['en', 'es', 'fr', 'ja'] });
```

## `projectId` [#project-id]

**Type** `string` · **Facultatif**

L’identifiant de votre projet General Translation, requis pour les services cloud de General Translation. Lorsqu’il est défini (sans `loadTranslations` personnalisé), il active le loader CDN qui récupère les traductions à l’exécution.

## `devApiKey` [#dev-api-key]

**Type** `string` · **Facultatif**

Une clé API de développement. Associée à un `projectId`, elle permet la traduction à l’exécution à la demande ainsi que le rechargement à chaud en développement, afin que [`getGT`](/docs/node/reference/functions/get-gt), [`getMessages`](/docs/node/reference/functions/get-messages) et [`tx`](/docs/node/reference/functions/tx) puissent traduire du nouveau contenu pendant le développement. Le rechargement à chaud fonctionne uniquement lorsque `NODE_ENV` n’est pas égal à `'production'`.

## `apiKey` [#api-key]

**Type** `string` · **Facultatif**

Une clé API de production. Définissez-la si vous avez besoin d’une traduction à l’exécution en production. Pour la plupart des déploiements, générez plutôt les traductions à l’avance avec la [CLI `gt`](/docs/cli/quickstart).

## `cacheUrl` [#cache-url]

**Type** `string | null` · **Facultatif** · **Par défaut** GT CDN

L’URL du service de cache des traductions. Définissez-la sur un hôte personnalisé pour charger les traductions depuis votre propre CDN, ou sur `null` pour désactiver le chargement du cache à distance.

## `runtimeUrl` [#runtime-url]

**Type** `string | null` · **Facultatif** · **Par défaut** runtime GT

L’URL du service de traduction à l’exécution utilisé par [`tx`](/docs/node/reference/functions/tx) et la traduction de développement à la demande. Définissez-la sur `null` ou `''` pour désactiver la traduction à l’exécution.

## `loadTranslations` [#load-translations]

**Type** `TranslationsLoader` · **Facultatif**

Une fonction personnalisée qui charge les traductions depuis votre propre source plutôt que depuis le CDN de General Translation. Elle reçoit un code de langue et renvoie les traductions correspondantes pour ce paramètre régional :

```ts
type TranslationsLoader = (locale: string) => Promise<unknown>;
```

```ts
initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es'],
  loadTranslations: async (locale) => {
    const res = await fetch(`https://my-api.com/translations/${locale}`);
    return res.json();
  },
});
```

## `customMapping` [#custom-mapping]

**Type** `CustomMapping` · **Facultatif**

Un mapping de codes de langue personnalisés vers des codes de langue standard ou des surcharges de [propriétés de paramètre régional](/docs/node/reference/functions/get-locale-properties). Utilisez-le pour attribuer un alias à un code (par exemple, `cn` vers `zh`) ou pour surcharger les propriétés d’affichage.

## `cacheExpiryTime` [#cache-expiry]

**Type** `number | null` · **Facultatif**

Durée de vie du cache des paramètres régionaux en millisecondes. Laissez-la non définie pour utiliser le TTL par défaut, définissez un nombre pour spécifier un TTL explicite, ou définissez `null` pour désactiver l’expiration.

## `dictionary` [#dictionary]

**Type** `Dictionary` · **Facultatif**

Un dictionnaire dans la langue source contenant des entrées de traduction indexées par id. Les entrées sont résolues à chaque requête avec [`getTranslations`](/docs/node/reference/functions/get-translations).

## `loadDictionary` [#load-dictionary]

**Type** `DictionaryLoader` · **Facultatif**

Un loader qui retourne un dictionnaire pour un paramètre régional donné :

```ts
type DictionaryLoader = (locale: string) => Promise<Dictionary>;
```

## `runtimeTranslation` [#runtime-translation]

**Type** `object` · **Facultatif** · **Par défaut** `timeout` 12000 ms

Paramètres de traduction à l’exécution appliqués par [`tx`](/docs/node/reference/functions/tx) et par la traduction de développement à la demande :

* `timeout?: number` — délai d’expiration de la requête, en millisecondes (par défaut : `12000`).
* `metadata?: object` — métadonnées fusionnées à chaque requête de traduction à l’exécution. C’est ici que doivent être renseignés les indices de traduction propres à l’exécution, notamment `modelProvider` (voir [`modelProvider`](#model-provider) ci-dessous) et `sourceLocale`.

## `batchConfig` [#batch-config]

**Type** `object` · **Facultatif**

Définit comment [`tx`](/docs/node/reference/functions/tx) et la traduction de développement à la demande regroupent par lots les requêtes de traduction à l’exécution. Laissez cette option non définie pour utiliser les valeurs par défaut.

* `maxConcurrentRequests?: number` — nombre maximal de requêtes de lot simultanées en cours.
* `maxBatchSize?: number` — nombre maximal d’entrées par requête de lot.
* `batchInterval?: number` — délai, en millisecondes, avant l’envoi d’un lot.

## `modelProvider` [#model-provider]

**Type** `string` · **Facultatif**

Correspond à la clé `modelProvider` de `gt.config.json`, que la [`CLI gt`](/docs/cli/quickstart) utilise pour sélectionner un modèle de traduction. Le runtime `gt-node` n’utilise **pas** cette clé de premier niveau — elle est acceptée uniquement pour éviter qu’un `gt.config.json` étendu avec l’opérateur spread ne provoque une erreur. Pour choisir le modèle utilisé par la traduction à l’exécution ([`tx`](/docs/node/reference/functions/tx)), définissez plutôt `modelProvider` dans le `metadata` de [`runtimeTranslation`](#runtime-translation).

## Exemple [#example]

```ts title="server.js"
import { initializeGT } from 'gt-node';

initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr', 'ja'],
  projectId: process.env.GT_PROJECT_ID,
});
```