Présentation

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 gtx-cli init créera pour vous un fichier gt.config.json dans votre projet.

Configuration

Le fichier gt.config.json accepte les propriétés suivantes, sans s’y limiter :

• defaultLocale : la locale par défaut de votre projet. C’est la locale dans laquelle votre contenu source est rédigé. C’est également la locale de secours pour votre projet (si vous utilisez gt-next ou gt-react).

• locales : un tableau de locales pour votre projet. Ce sont les locales vers lesquelles vous souhaitez traduire votre projet. Consultez les locales prises en charge pour en savoir plus. Si vous utilisez gt-next ou gt-react, ce sont également les locales prises en charge par votre application.

• files : un objet qui contient des informations sur le contenu que vous souhaitez traduire.

• stageTranslations : indicateur booléen facultatif indiquant si votre projet est configuré pour utiliser une relecture humaine.

• src : un tableau facultatif de motifs de glob de fichiers pour vos fichiers source. Par défaut, défini sur :

[
  "src/**/*.{js,jsx,ts,tsx}",
  "app/**/*.{js,jsx,ts,tsx}",
  "pages/**/*.{js,jsx,ts,tsx}",
  "components/**/*.{js,jsx,ts,tsx}"
]

• dictionary : Une chaîne facultative qui indique le chemin relatif vers le fichier dictionary.

{
  "$schema": "https://assets.gtx.dev/config-schema.json",
}

Voici un squelette du fichier 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"
}

Aliasing de locale

Si vous souhaitez créer un alias pour une locale (p. ex. cn au lieu de zh), vous pouvez définir un mapping personnalisé dans le fichier gt.config.json.

{
  "customMapping": {
    "cn": {
      "code": "zh",
    }
  }
}

Vous pouvez également spécifier différents attributs pour le locale aliasé.

{
  "customMapping": {
    "cn": {
      "code": "zh",
      "name": "Mandarin",
    }
  }
}

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 mélanger différents types de fichiers et les faire tous traduire. Nous prenons actuellement en charge les types de fichiers suivants :

• gt : files General Translation.
• json : files JSON.
• yaml : files YAML.
• mdx : files de composants Markdown (MDX).
• md : files Markdown (MD).
• js : files JavaScript.
• ts : files TypeScript.

Chaque type de fichier doit correspondre à un objet contenant une ou plusieurs des clés suivantes :

• include
• exclude
• transform
• output

include

S’il est utilisé, la valeur de la clé include doit être un tableau de motifs glob qui correspondent 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 soient trouvés correctement et que les fichiers traduits soient enregistrés au bon emplacement. L’outil CLI remplacera l’espace réservé [locale] par la valeur defaultLocale lors de la recherche de fichiers traduisibles.

L’outil CLI enregistrera les fichiers traduits dans le chemin correspondant, avec l’espace réservé [locale] remplacé par le code de locale cible.

{
  "include": ["docs/[locale]/**/*.json"]
}

exclude

S’il est utilisé, la valeur de la clé exclude doit être un tableau de motifs glob correspondant aux files que vous souhaitez exclure de la traduction.

Le motif est identique à celui de include, à la différence que l’espace réservé [locale] est facultatif. S’il est fourni, il sera remplacé par la valeur de defaultLocale.

{
  "exclude": ["docs/[locale]/exclude/**/*.json"]
}

Si vous souhaitez exclure des files de la traduction pour toutes les locales, vous pouvez utiliser l’espace réservé [locales] au lieu de [locale].

{
  "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 un renommage du nom de fichier. Il 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 souhaitez que l’extension de tous vos files traduits soit .[locale].json au lieu de .json, vous pouvez utiliser la configuration suivante :

{
  "transform": "*.[locale].json"
}

Sinon, si transform est un objet, il doit contenir les propriétés suivantes :

• match (optionnel) : un motif regex pour faire correspondre des chaînes, avec prise en charge des groupes de capture
• replace (requis) : une chaîne ou un motif regex pour remplacer la correspondance

Les deux valeurs prennent en charge les groupes de capture regex et sont appliquées au nom de fichier relatif complet du fichier de sortie.

{
  "transform": {
    "match": "^(.*)$",
    "replace": "{locale}/$1"
  }
}

Par exemple, la configuration ci-dessus fera enregistrer les files traduits dans un sous-répertoire du locale 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 locale qui se comporte différemment selon le contexte :
  • Dans les chaînes match : Remplacé par le code de locale par défaut (par exemple, "en") pour aider à identifier les fichiers sources
  • Dans les chaînes replace : Remplacé par le code de locale cible (par exemple, "fr", "es") pour les fichiers de sortie traduits

Par exemple, si votre locale 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.

output

Cette clé est exclusivement utilisée pour les files de General Translation, spécifiquement pour enregistrer des traductions en local. Si vous utilisez le CDN (Content Delivery Network, réseau de diffusion de contenu) de GT, cette clé n’est pas nécessaire.

La value doit être une chaîne 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 file appelé ui.es.json dans le répertoire public/i18n, vous devez utiliser la chaîne suivante :

{
  "output": "public/i18n/[locale].json"
}

Type de fichier : gt

Clés prises en charge

• output (obligatoire)

Exemple

{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "gt": {
      "output": "public/i18n/[locale].json"
    },
  }
}

Cette configuration permettra à 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 publiera pas vos traductions sur le CDN (réseau de diffusion de contenu) de GT.

Type de fichier : json

Clés prises en charge

• include (obligatoire)
• exclude (facultatif)
• transform (facultatif)

Exemple

{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "json": {
      "include": ["json_files/[locale]/**/*.json"],
      "exclude": ["json_files/[locale]/exclude/**/*.json"]
    }
  }
}

Disons que la locale par défaut de votre projet est en, et que vous souhaitez traduire votre projet en fr et es.

Avec cette configuration, la 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/.

Elle ignorera tous les fichiers dans le sous-répertoire json_files/en/exclude/.

Type de fichier : yaml

Clés prises en charge

• include (Obligatoire)
• exclude (Facultatif)
• transform (Facultatif)

Exemple

{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "yaml": {
      "include": ["yaml_files/[locale]/**/*.yaml"],
      "exclude": ["yaml_files/[locale]/exclude/**/*.yaml"]
    }
  }
}

Disons que la locale par défaut de votre projet est en, et que vous souhaitez traduire votre projet en fr et es.

Avec cette configuration, la 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/.

Elle ignorera tous les fichiers dans le sous-répertoire yaml_files/en/exclude/.

Type de fichier : mdx

Clés prises en charge

• include (Obligatoire)
• exclude (Facultatif)
• transform (Facultatif)

Exemple

{
  "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 modifie l’extension des fichiers traduits en .ja.mdx.

Type de fichier : md

Clés prises en charge

• include (Requis)
• exclude (Facultatif)
• transform (Facultatif)

Exemple

{
  "defaultLocale": "en",
  "locales": ["ja"],
  "files": {
    "md": {
      "include": ["content/docs/[locale]/**/*.md"],
      "exclude": ["content/docs/[locale]/exclude/**/*.md"],
      "transform": "*.[locale].md"
    }
  }
}

Cette configuration indiquera à 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 modifie l’extension des fichiers traduits en .ja.md.

Tous les fichiers du répertoire content/docs/en/exclude seront ignorés.

Type de fichier : js

Clés prises en charge

• include (obligatoire)
• exclude (facultatif)
• transform (facultatif)

Exemple

{
  "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.

La clé transform modifie l’extension des fichiers traduits en .fr.js et .es.js respectivement (au lieu de .js).

Type de fichier : ts

Clés prises en charge

• include (Obligatoire)
• exclude (Optionnel)
• transform (Optionnel)

Exemple

{ 
  "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.

La clé transform modifie l’extension des fichiers traduits en .fr.ts et .es.ts respectivement (au lieu de .ts).

Exemple de configuration

Analysons un exemple de fichier 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 à gtx-cli translate :

• Tous les fichiers MDX dans le répertoire content/docs/en.
• Tous les fichiers JSON dans le répertoire resources/en (à l’exclusion de tout fichier dans le répertoire resources/en/exclude).
• Tous les composants <T> en ligne dans 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. Ces fichiers peuvent être chargés à l’aide de loadTranslations.

MDX : Les traductions seront enregistrées dans les répertoires content/docs/fr et content/docs/es. Les extensions de fichier seront modifiées en .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 pour générer ce fichier de configuration.