# gt-node: General Translation Node.js SDK: Configuration URL: https://generaltranslation.com/fr/docs/node/reference/config.mdx Docs index: https://generaltranslation.com/llms.txt 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`, mais utilise les variables d’environnement comme contenu de secours pour les identifiants d’accès. Cette page documente les propriétés acceptées par cet appel. ## Vue d’ensemble [#overview] Appelez [`initializeGT`](/docs/node/reference/functions/initialize-gt) 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'], }); ``` Les clés correspondent à celles que lit la [CLI gt](/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. ## Variables d’environnement [#env] Les valeurs explicites fournies à [`initializeGT`](/docs/node/reference/functions/initialize-gt) priment sur les variables d’environnement. | Variable | Description | | ---------------- | ---------------------------------------------------------- | | `GT_PROJECT_ID` | ID du projet utilisé si `projectId` est omis. | | `GT_DEV_API_KEY` | Clé API de développement utilisée si `devApiKey` est omis. | | `GT_API_KEY` | Clé API de production utilisée si `apiKey` est omis. | ## 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 | `GT_PROJECT_ID` si défini | | [`devApiKey`](#dev-api-key) | Clé API de développement pour la traduction à la demande. | `string` | Oui | `GT_DEV_API_KEY` si défini | | [`apiKey`](#api-key) | Clé API de production. | `string` | Oui | `GT_API_KEY` si défini | | [`cacheUrl`](#cache-url) | Hôte du cache des traductions. `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 des paramètres régionaux, en millisecondes. `null` désactive l’expiration. | `number \| null` | Oui | — | | [`dictionary`](#dictionary) | Dictionnaire dans la 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`](/docs/node/reference/functions/initialize-gt) 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.* ## Identifiants depuis l’environnement [#environment] Lorsqu’un identifiant est omis de l’objet de configuration, [`initializeGT`](/docs/node/reference/functions/initialize-gt) lit la variable d’environnement correspondante : | Option | Variable d’environnement | Priorité | | ----------- | ------------------------ | --------------------------------------------- | | `projectId` | `GT_PROJECT_ID` | Option explicite non vide, puis environnement | | `devApiKey` | `GT_DEV_API_KEY` | Option explicite non vide, puis environnement | | `apiKey` | `GT_API_KEY` | Option explicite non vide, puis environnement | Une chaîne explicite vide est traitée comme absente et utilise alors la valeur de l’environnement. Les autres champs de configuration, y compris locales et les chargeurs de traduction, ne sont pas lus depuis l’environnement. ## `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** · **Par défaut** `GT_PROJECT_ID` si défini L’ID du projet General Translation, requis pour les services cloud de General Translation. Lorsqu’il est omis, il se replie sur `GT_PROJECT_ID`. 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** · **Par défaut** `GT_DEV_API_KEY` si défini Une clé API de développement. Lorsqu’elle est omise, elle se replie sur `GT_DEV_API_KEY`. 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 dans un environnement de développement, c’est-à-dire lorsque `NODE_ENV` est exactement égal à `'development'`, lorsque `import.meta.env.MODE` est égal à `'development'` ou lorsque `import.meta.env.DEV` est égal à `true`. Toute autre valeur est considérée comme étant de production, y compris lorsque `NODE_ENV` n’est pas défini ; définissez donc `NODE_ENV=development` pour le rechargement à chaud. ## `apiKey` [#api-key] **Type** `string` · **Facultatif** · **Par défaut** `GT_API_KEY` si défini Une clé API de production. Lorsqu’elle est omise, elle se replie sur `GT_API_KEY`. 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; ``` ```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`](/docs/platform/core/reference/types/custom-mapping) · **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; ``` ## `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'], // Les identifiants sont lus depuis GT_PROJECT_ID, GT_API_KEY et GT_DEV_API_KEY. }); ``` ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.