# gt: General Translation CLI tool: Configuration URL: https://generaltranslation.com/fr/docs/cli/reference/config.mdx --- title: Configuration description: Documentation de configuration du fichier gt.config.json --- ## Vue d’ensemble Le fichier `gt.config.json` sert à configurer les paramètres GT de votre projet. Il doit être placé à la racine du projet. L’assistant de configuration de la CLI [`npx gt init`](/docs/cli/init) créera un fichier `gt.config.json` dans votre projet. ## Configuration Le fichier `gt.config.json` accepte notamment les propriétés suivantes : * `defaultLocale` : Le paramètre régional par défaut de votre projet. C’est dans ce paramètre régional que votre contenu source est rédigé. Il s’agit aussi du paramètre régional de repli de votre projet (si vous utilisez `gt-next` ou `gt-react`). * `locales` : Un tableau de paramètres régionaux pour votre projet. Il s’agit des paramètres régionaux vers lesquels vous souhaitez traduire votre projet. Consultez les [configurations régionales compatibles](/docs/platform/supported-locales) pour plus d’informations. Si vous utilisez `gt-next` ou `gt-react`, ce sont aussi les paramètres régionaux pris en charge par votre application. * `files` : Objet contenant des informations sur le contenu que vous souhaitez traduire. * `publish` : Indicateur booléen facultatif. Lorsqu’il vaut `true`, les fichiers traduits sont publiés sur le CDN de GT après l’exécution de `translate`, `upload` ou `save-local`. La valeur par défaut est `false` (aucune publication). Peut aussi être défini pour chaque commande avec `--publish`. Consultez [la publication sur le CDN](#cdn-publishing) pour plus de détails. * `stageTranslations` : Indicateur booléen facultatif indiquant si votre projet est configuré pour utiliser une révision humaine. * `src` : Tableau facultatif de motifs de type glob pour vos fichiers source. Par défaut, il est défini sur : ```json [ "src/**/*.{js,jsx,ts,tsx}", "app/**/*.{js,jsx,ts,tsx}", "pages/**/*.{js,jsx,ts,tsx}", "components/**/*.{js,jsx,ts,tsx}" ] ``` * `dictionary` : une chaîne de caractères facultative qui indique le chemin relatif vers le fichier de dictionnaire. * `branchOptions` : un objet facultatif permettant de configurer le suivi des traductions par branche. Consultez [branching](/docs/cli/branching) pour plus de détails. Pour vous aider à valider votre fichier `gt.config.json`, vous pouvez utiliser le [schéma JSON](https://assets.gtx.dev/config-schema.json) pour la CLI. Ajoutez-le en haut de votre fichier `gt.config.json` : ```json title="gt.config.json" copy { "$schema": "https://assets.gtx.dev/config-schema.json" } ``` Voici une structure de base du fichier `gt.config.json` : ```json title="gt.config.json" { "$schema": "https://assets.gtx.dev/config-schema.json", "defaultLocale": "en", "locales": ["fr", "es"], "files": { "gt": { "output": "..." }, "json": { "include": [...] }, "mdx": { "include": [...] }, "md": { "include": [...] } }, "src": [ "src/**/*.{ts,tsx}", ], "dictionary": "./dictionary.json" } ``` ### Alias de paramètre régional Si vous souhaitez utiliser un alias pour un paramètre régional (par ex. `cn` au lieu de `zh`), vous pouvez définir une correspondance personnalisée dans le fichier `gt.config.json`. ```json title="gt.config.json" { "customMapping": { // L'alias de paramètre régional "cn": { "code": "zh" // Le code de langue BCP 47 officiel } } } ``` Vous pouvez également spécifier des attributs différents pour le paramètre régional associé à un alias. ```json title="gt.config.json" { "customMapping": { "cn": { "code": "zh", "name": "Mandarin" } } } ``` ### Options de branche Si vous souhaitez configurer les paramètres de branche dans votre fichier de configuration, vous pouvez utiliser l’objet `branchOptions` : ```json title="gt.config.json" { "branchOptions": { "enabled": true, "currentBranch": "my-feature-branch", "autoDetectBranches": true, "remoteName": "origin" } } ``` | Propriété | Description | Par défaut | | -------------------- | -------------------------------------------------------------------------------------- | ----------- | | `enabled` | Active la branche pour le projet | `false` | | `currentBranch` | Remplace le nom de la branche actuelle (au lieu de le détecter automatiquement) | `undefined` | | `autoDetectBranches` | Détecte automatiquement les relations entre branches (branches entrantes et extraites) | `true` | | `remoteName` | Nom du remote Git utilisé pour la détection des branches | `"origin"` | Les flags CLI priment sur les options du fichier de configuration. Consultez le [guide du branching](/docs/cli/branching) pour plus de détails. *** ## `files` ### Types de fichiers pris en charge `files` doit contenir une clé pour chaque type de fichier que vous souhaitez traduire. Vous pouvez configurer votre projet pour combiner différents types de fichiers et tous les traduire. Nous prenons actuellement en charge les types de fichiers suivants : * `gt` : fichiers General Translation. Utilisés par [`gt-next`](/docs/next), [`gt-react`](/docs/react) et [`gt-react-native`](/docs/react-native). * `json` : fichiers JSON. * `pot` : fichiers PO/POT (gettext). * `yaml` : fichiers YAML. * `mdx` : fichiers de composants Markdown (MDX). * `md` : fichiers Markdown (MD). * `js` : fichiers JavaScript. * `ts` : fichiers TypeScript. * `html` : fichiers HTML. * `txt` : fichiers texte. * `twilioContentJson` : fichiers JSON Twilio Content. Utilisés pour traduire les [Twilio Content Templates](https://www.twilio.com/docs/content). Chaque type de fichier doit correspondre à un objet contenant une ou plusieurs des clés suivantes : * `include` * `exclude` * `transform` * `transformationFormat` * `output` ### `include` Si elle est utilisée, la valeur de la clé `include` doit être un tableau de motifs glob correspondant aux fichiers que vous souhaitez traduire. Vous devez utiliser l’espace réservé `[locale]` dans vos motifs glob afin de garantir que les fichiers source sont correctement trouvés et que les fichiers traduits sont enregistrés au bon emplacement. L’outil CLI remplacera l’espace réservé `[locale]` par la valeur `defaultLocale` lors de la recherche des fichiers à traduire. L’outil CLI enregistrera les fichiers traduits dans le chemin correspondant, en remplaçant l’espace réservé `[locale]` par le code de langue cible. ```json { "include": ["docs/[locale]/**/*.json"] } ``` ### `exclude` Si elle est utilisée, la valeur de la clé `exclude` doit être un tableau de motifs glob correspondant aux fichiers que vous souhaitez exclure de la traduction. Le motif est le même que pour `include`, à ceci près que l’espace réservé `[locale]` est facultatif. S’il est fourni, il sera remplacé par la valeur de `defaultLocale`. ```json { "exclude": ["docs/[locale]/exclude/**/*.json"] } ``` Si vous souhaitez exclure des fichiers de la traduction pour tous les paramètres régionaux, vous pouvez utiliser l’espace réservé `[locales]` au lieu de `[locale]`. ```json { "exclude": ["docs/[locales]/exclude/**/*.json"] } ``` ### `transform` `transform` peut être soit une chaîne de caractères, soit un objet. Si `transform` est une chaîne de caractères, il définit une réécriture du nom de fichier. Elle doit contenir un caractère générique `*` qui sera remplacé par le nom de fichier d’origine (tout ce qui précède le premier `.`). Par exemple, si vous voulez que l’extension de tous vos fichiers traduits soit `.[locale].json` au lieu de `.json`, vous pouvez utiliser la configuration suivante : ```json { "transform": "*.[locale].json" } ``` Sinon, si `transform` est un objet, il doit contenir les propriétés suivantes : * `match` (facultatif) : un motif regex pour faire correspondre des chaînes de caractères, avec prise en charge des groupes de capture * `replace` (obligatoire) : chaîne de caractères ou motif regex pour remplacer la correspondance Les deux valeurs prennent en charge les groupes de capture regex et s’appliquent au nom de fichier relatif complet du fichier de sortie. ```json { "transform": { "match": "^(.*)$", "replace": "{locale}/$1" } } ``` Par exemple, la configuration ci-dessus aura pour effet d’enregistrer les fichiers traduits dans un sous-répertoire du paramètre régional cible. #### Espaces réservés spéciaux L’option `transform` prend en charge plusieurs espaces réservés spéciaux qui peuvent être utilisés dans les chaînes `match` et `replace` : * `{locale}` : l’espace réservé du code de langue, dont le comportement varie selon le contexte : * **Dans les chaînes `match`** : remplacé par le code de langue du paramètre régional par défaut (par ex. `"en"`) pour aider à identifier les fichiers source * **Dans les chaînes `replace`** : remplacé par le code de langue du paramètre régional cible (par ex. `"fr"`, `"es"`) pour les fichiers de sortie traduits Par exemple, si votre paramètre régional par défaut est `"en"` et que vous traduisez vers `"fr"` : * Un motif `match` de `"content/{locale}/file.md"` devient `"content/en/file.md"` * Un motif `replace` de `"content/{locale}/file.md"` devient `"content/fr/file.md"` De plus, toute autre propriété de `getLocaleProperties` peut être utilisée comme espace réservé avec le même comportement dépendant du contexte. Cela est utile si votre documentation ou votre framework i18n exige une extension de fichier spécifique pour les fichiers traduits, au lieu d’un routage par paramètre régional basé sur des sous-répertoires. ### `transformationFormat` La clé `transformationFormat` spécifie un format de fichier différent pour les fichiers de sortie traduits. C’est utile lorsque vos fichiers source sont des templates qui doivent générer un type de fichier différent après la traduction. Par exemple, les fichiers POT (PO Template) sont des templates source, mais les fichiers traduits générés doivent être des fichiers PO : ```json { "files": { "pot": { "include": ["locales/[locale]/**/*.pot"], "transformationFormat": "PO" } } } ``` La valeur doit être une chaîne de caractères correspondant à l’une des clés de formats de fichier pris en charge (par ex., `"PO"`). ### `output` Cette clé est utilisée exclusivement pour les fichiers General Translation, plus précisément pour enregistrer les traductions en local. Si vous utilisez le CDN de GT, cette clé n’est pas nécessaire. La valeur doit être une chaîne de caractères contenant un espace réservé `[locale]` indiquant l’emplacement où les traductions seront enregistrées. Par exemple, si vous souhaitez enregistrer vos traductions en espagnol dans un fichier nommé `ui.es.json` dans le répertoire `public/i18n`, vous devez utiliser la chaîne de caractères suivante : ```json { "output": "public/i18n/[locale].json" } ``` Cette option ne doit être utilisée que si vous utilisez `gt-next` ou `gt-react` et souhaitez enregistrer les traductions localement, au lieu d’utiliser le CDN de GT. Actuellement, un seul fichier peut être généré par paramètre régional. *** ### Type de fichier : `gt` [#gt] **Clés prises en charge** * `output` (obligatoire) **Exemple** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["fr", "es"], "files": { "gt": { "output": "public/i18n/[locale].json" } } } ``` Cette configuration indique à l’outil CLI d’enregistrer vos traductions en français et en espagnol dans le répertoire `public/i18n/[locale].json`. Par défaut, avec cette configuration, l’outil CLI ne publie pas vos traductions sur le CDN de GT. *** ### Type de fichier : `json` [#json] **Clés prises en charge** * `include` (obligatoire) * `exclude` (facultatif) * `transform` (facultatif) **Exemple** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["fr", "es"], "files": { "json": { "include": ["json_files/[locale]/**/*.json"], "exclude": ["json_files/[locale]/exclude/**/*.json"] } } } ``` Supposons que le paramètre régional par défaut de votre projet soit `en` et que vous souhaitiez traduire votre projet en `fr` et `es`. Avec cette configuration, le CLI recherchera tous les fichiers JSON dans le sous-répertoire `json_files/en/` et enregistrera les fichiers traduits dans `json_files/fr/` et `json_files/es/`. Il ignorera tous les fichiers du sous-répertoire `json_files/en/exclude/`. *** ### Type de fichier : `yaml` [#yaml] **Clés prises en charge** * `include` (obligatoire) * `exclude` (facultatif) * `transform` (facultatif) **Exemple** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["fr", "es"], "files": { "yaml": { "include": ["yaml_files/[locale]/**/*.yaml"], "exclude": ["yaml_files/[locale]/exclude/**/*.yaml"] } } } ``` Supposons que le paramètre régional par défaut de votre projet soit `en` et que vous souhaitiez le traduire en `fr` et `es`. Avec cette configuration, le CLI recherchera tous les fichiers YAML dans le sous-répertoire `yaml_files/en/` et enregistrera les fichiers traduits dans `yaml_files/fr/` et `yaml_files/es/`. Il ignorera tous les fichiers du sous-répertoire `yaml_files/en/exclude/`. *** ### Type de fichier : `mdx` [#mdx] **Clés prises en charge** * `include` (obligatoire) * `exclude` (facultatif) * `transform` (facultatif) **Exemple** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["ja"], "files": { "mdx": { "include": ["content/docs/[locale]/**/*.mdx"], "transform": "*.[locale].mdx" } } } ``` Cette configuration indique à l’outil CLI de rechercher tous les fichiers MDX dans le répertoire `content/docs/en` et d’enregistrer les fichiers traduits dans le répertoire `content/docs/ja`. La clé `transform` fait passer l’extension des fichiers traduits à `.ja.mdx`. *** ### Type de fichier : `md` [#md] **Clés prises en charge** * `include` (obligatoire) * `exclude` (facultatif) * `transform` (facultatif) **Exemple** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["ja"], "files": { "md": { "include": ["content/docs/[locale]/**/*.md"], "exclude": ["content/docs/[locale]/exclude/**/*.md"], "transform": "*.[locale].md" } } } ``` Cette configuration indique à l’outil CLI de rechercher tous les fichiers MD dans le répertoire `content/docs/en` et d’enregistrer les fichiers traduits dans le répertoire `content/docs/ja`. La clé `transform` fait en sorte que l’extension des fichiers traduits soit remplacée par `.ja.md`. Tous les fichiers du répertoire `content/docs/en/exclude` seront ignorés. *** ### Type de fichier : `js` [#js] **Clés prises en charge** * `include` (obligatoire) * `exclude` (facultatif) * `transform` (facultatif) **Exemple** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["fr", "es"], "files": { "js": { "include": ["scripts/[locale]/**/*.js"] } } } ``` Cette configuration indiquera à l’outil CLI de rechercher tous les fichiers JavaScript dans le répertoire `scripts/en` et d’enregistrer les fichiers traduits dans les répertoires `scripts/fr` et `scripts/es`. *** ### Type de fichier : `ts` [#ts] **Clés prises en charge** * `include` (obligatoire) * `exclude` (facultatif) * `transform` (facultatif) **Exemple** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["fr", "es"], "files": { "ts": { "include": ["scripts/[locale]/**/*.ts"] } } } ``` Cette configuration indique à l’outil CLI de rechercher tous les fichiers TypeScript dans le répertoire `scripts/en` et d’enregistrer les fichiers traduits dans les répertoires `scripts/fr` et `scripts/es`. *** ### Type de fichier : `html` [#html] **Clés prises en charge** * `include` (obligatoire) * `exclude` (facultatif) * `transform` (facultatif) **Exemple** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["ja"], "files": { "html": { "include": ["content/docs/[locale]/**/*.html"], "exclude": ["content/docs/[locale]/exclude/**/*.html"], "transform": "*.[locale].html" } } } ``` Cette configuration indique à l’outil CLI de rechercher tous les fichiers HTML dans le répertoire `content/docs/en` et d’enregistrer les fichiers traduits dans le répertoire `content/docs/ja`. La clé `transform` modifie l’extension des fichiers traduits en `.ja.html`. Tous les fichiers du répertoire `content/docs/en/exclude` seront ignorés. *** ### Type de fichier : `txt` [#txt] **Clés prises en charge** * `include` (obligatoire) * `exclude` (facultatif) * `transform` (facultatif) **Exemple** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["ja"], "files": { "txt": { "include": ["content/docs/[locale]/**/*.txt"], "exclude": ["content/docs/[locale]/exclude/**/*.txt"], "transform": "*.[locale].txt" } } } ``` Cette configuration indique à l’outil CLI de rechercher tous les fichiers texte dans le répertoire `content/docs/en` et d’enregistrer les fichiers traduits dans le répertoire `content/docs/ja`. La clé `transform` modifie l’extension des fichiers traduits en `.ja.txt`. Tous les fichiers du répertoire `content/docs/en/exclude` sont ignorés. *** ### Type de fichier : `twilioContentJson` [#twilioContentJson] **Clés prises en charge** * `include` (obligatoire) * `exclude` (facultatif) * `transform` (facultatif) **Exemple** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["es", "fr"], "files": { "twilioContentJson": { "include": ["twilio/[locale]/**/*.json"] } } } ``` Cette configuration indique à l’outil CLI qu’il doit rechercher tous les fichiers JSON Twilio Content dans le répertoire `twilio/en` et enregistrer les fichiers traduits dans les répertoires `twilio/es` et `twilio/fr`. Les fichiers JSON Twilio Content sont des templates structurés utilisés par le [Content Template Builder de Twilio](https://www.twilio.com/docs/content) pour la messagerie WhatsApp, SMS et RCS. La CLI traduit les valeurs textuelles destinées à l’utilisateur (texte du corps, libellés des boutons, titres des cartes) tout en préservant la structure du template, les espaces réservés de variables et les champs non traduisibles. *** ## Publication sur le CDN [#cdn-publishing] Par défaut, la CLI ne publie pas les fichiers traduits sur le CDN de GT. Si vous avez activé le CDN dans les paramètres du projet, vous pouvez contrôler la publication de façon globale, par fichier ou par commande. ### Option globale de publication Définissez `publish` au niveau supérieur pour publier **tous** les fichiers traduits sur le CDN : ```json title="gt.config.json" { "publish": true } ``` Vous pouvez également ajouter `--publish` aux commandes `translate`, `upload` ou `save-local` : ```bash npx gt translate --publish ``` ### Option `publish` du JSON GT Pour publier uniquement le format de traduction interne de GT, utilisez la clé `publish` dans `files.gt` : ```json title="gt.config.json" { "files": { "gt": { "output": "public/i18n/[locale].json", "publish": true } } } ``` ### Contrôle de la publication par fichier Pour les autres types de fichiers (`json`, `yaml`, `mdx`, `md`, `po`, `xliff`, `csv`, `properties`), vous pouvez contrôler la publication pour chaque fichier en utilisant un objet dans le tableau `include` au lieu d'une simple chaîne glob : ```json title="gt.config.json" { "files": { "json": { "include": [ { "pattern": "locales/[locale]/*.json", "publish": true }, { "pattern": "locales/[locale]/internal/**/*.json", "publish": false } ] } } } ``` Chaque entrée de `include` peut être soit : * Une **chaîne de caractères** — un motif glob (aucune préférence de publication ; utilise le paramètre global `publish`) * Un **objet** avec `pattern` (glob) et `publish` (booléen) — inclut ou exclut explicitement de la publication les fichiers correspondants ### Ordre de résolution Pour un fichier donné, la CLI détermine s’il doit être publié selon l’ordre suivant : 1. **Exclusion explicite** — le fichier correspond à une entrée `include` avec `"publish": false` → non publié ou supprimé du CDN 2. **Inclusion explicite** — le fichier correspond à une entrée `include` avec `"publish": true` → publié sur le CDN 3. **Valeur de repli globale** — utilise le paramètre `publish` de niveau supérieur (vaut `false` par défaut s’il n’est pas défini) Si aucune configuration de publication n’existe à aucun niveau, l’étape de publication est entièrement ignorée. *** ## Exemple de configuration Examinons un exemple de fichier `gt.config.json` : ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["fr", "es"], "files": { "gt": { "output": "public/i18n/[locale].json" }, "mdx": { "include": ["content/docs/[locale]/**/*.mdx"], "transform": "*.[locale].mdx" }, "json": { "include": ["resources/[locale]/**/*.json"], "exclude": ["resources/[locale]/exclude/**/*.json"] } } } ``` Dans cet exemple, nous traduisons les fichiers suivants avec un seul appel à [`gt translate`](/docs/cli/translate) : * Tous les fichiers MDX du répertoire `content/docs/en`. * Tous les fichiers JSON du répertoire `resources/en` (à l’exception des fichiers du répertoire `resources/en/exclude`). * Tous les composants `` inline de votre projet React ou Next.js. * Votre fichier `dictionary.[json|js|ts]`. GT : les traductions seront enregistrées dans `public/i18n/es.json` et `public/i18n/fr.json`. Vous pouvez charger ces fichiers avec [`loadTranslations`](/docs/react/api/config/load-translations). MDX : les traductions seront enregistrées dans les répertoires `content/docs/fr` et `content/docs/es`. Les extensions de fichier seront remplacées par `.fr.mdx` et `.es.mdx` respectivement (au lieu de `.mdx`). JSON : les traductions seront enregistrées dans les répertoires `resources/fr` et `resources/es`. *** ## Prochaines étapes Découvrez comment utiliser la [commande init](/docs/cli/init) pour générer ce fichier de configuration.