Aperçu

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

Configuration

Le fichier gt.config.json accepte notamment les propriétés suivantes :

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

• locales: Un tableau des langues de votre projet. Ce sont les langues dans lesquelles vous souhaitez traduire votre projet. Consultez la liste des langues prises en charge pour plus d’informations. Si vous utilisez gt-next ou gt-react, ce sont également les langues prises en charge par votre application.

• files: Objet contenant les informations sur le contenu que vous souhaitez traduire.

• stageTranslations: Indicateur booléen optionnel précisant si votre projet est configuré pour une relecture humaine.

• src: Tableau optionnel de motifs glob pour vos fichiers source. Par défaut :

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

• dictionary: Chaîne optionnelle indiquant le chemin relatif vers le fichier de dictionnaire.

{
  "$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"
}

Alias de paramètres régionaux

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

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

Vous pouvez également définir des attributs différents pour la locale aliasée.

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

• gt : fichiers de traduction générale.
• json : fichiers JSON.
• yaml : fichiers YAML.
• mdx : fichiers de composants Markdown (MDX).
• md : fichiers Markdown (MD).
• js : fichiers JavaScript.
• ts : fichiers 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 correspondant aux fichiers que vous souhaitez traduire.

Vous devez utiliser l’espace réservé [locale] dans vos motifs glob pour vous assurer que les fichiers source sont correctement trouvés et que les fichiers traduits sont enregistrés au bon endroit. L’outil CLI remplacera l’espace réservé [locale] par la valeur de defaultLocale lors de la recherche des fichiers traduisibles.

L’outil CLI enregistrera les fichiers traduits dans le chemin correspondant, avec l’espace réservé [locale] remplacé par le code de la langue 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 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.

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

Si vous souhaitez exclure des fichiers 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, il définit un renommage 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 souhaitez que l’extension de tous vos fichiers 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) : motif regex pour faire correspondre des chaînes, avec prise en charge des groupes de capture
• replace (obligatoire) : chaîne 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.

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

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

Par exemple, si votre langue 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 uniquement utilisée pour les fichiers de traduction générale, spécifiquement pour enregistrer les traductions en local. Si vous utilisez le CDN GT, cette clé n’est pas nécessaire.

La valeur doit être une chaîne contenant l’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 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 permet à 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 de GT.

Type de fichier : json

Clés prises en charge

• include (obligatoire)
• exclude (optionnel)
• transform (optionnel)

Exemple

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

Supposons que la langue par défaut de votre projet soit en et que vous souhaitiez 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"]
    }
  }
}

Supposons que la langue par défaut de votre projet soit en et que vous souhaitiez traduire votre projet en fr et es.

Avec cette configuration, l’interface en ligne de commande 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 (Obligatoire)
• exclude (Optionnel)
• transform (Optionnel)

Exemple

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

Cette configuration demande à 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 indique à 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

Examinons un fichier gt.config.json d’exemple :

{
  "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 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 <T> 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 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 pour générer ce fichier de configuration.