JSON

Traduisez les valeurs textuelles imbriquées en choisissant les chemins à copier, à conserver, à omettre ou à mettre à jour.

Dans un catalogue JSON, l’application recherche une clé et affiche sa valeur. Le gestionnaire de fichiers json modifie les valeurs textuelles tout en conservant les clés des objets, les positions dans les tableaux, les nombres, les booléens et les valeurs nulles comme données. Il reconstruit la cible à partir de la source actuelle, en y insérant de nouvelles traductions ou du texte cible conservé.

Le gestionnaire prend en charge les catalogues composés d’objets et de tableaux imbriqués, ainsi qu’une chaîne à la racine. La CLI déduit json de .json. Configurez la source dans la configuration de la CLI ou via la GitHub App.

Ce qui devient une tâche de traduction #

Par exemple :

json
{
  "checkout": {
    "title": "Complete your order",
    "delivery": "Delivery within {days} days"
  },
  "plans": [
    { "name": "Personal", "seats": 1 },
    { "name": "Team", "seats": 10 }
  ],
  "enabled": true
}

Le gestionnaire sélectionne checkout.title, checkout.delivery, plans[0].name et plans[1].name. Il laisse les nombres seats et le booléen enabled inchangés. Protégez explicitement les identifiants dont la valeur est une chaîne : le type JSON d’une valeur indique au gestionnaire qu’il s’agit de texte, mais pas si ce texte est destiné à être lu.

La notation abrégée des chemins utilise des points pour parcourir les objets et des crochets pour désigner les positions dans les tableaux : checkout.title sélectionne une valeur imbriquée et plans[0].name sélectionne le nom du premier forfait. Pour une clé dont le nom est littéralement checkout.title, utilisez la notation JSONPath entre guillemets $['checkout.title']. Consultez les options de contrôle des clés pour connaître la syntaxe de sélection.

Comment les mises à jour réutilisent les traductions existantes #

Une exécution incrémentielle utilise trois entrées distinctes :

EntréeRôle
Source actuelleDéfinit la structure et les chaînes de la nouvelle sortie.
Source précédentePermet de déterminer si la chaîne source située au chemin correspondant a changé.
Cible existanteFournit les traductions qui peuvent être conservées.

Lorsque la source précédente et la cible existante sont disponibles, toute chaîne source nouvelle ou modifiée devient une tâche de traduction. Pour une chaîne source inchangée, la valeur cible existante au chemin correspondant peut être réutilisée. Deux clés contenant le même texte anglais restent des enregistrements distincts ; leurs traductions acceptées peuvent différer, car leurs contextes sont différents.

Par exemple, modifier checkout.title n’impose pas à lui seul de retraduire checkout.delivery. Si la valeur source de ce dernier n’a pas changé et que sa valeur cible est disponible, celle-ci peut être reprise telle quelle. La modification d’un nombre ou d’une autre donnée structurelle peut toutefois nécessiter de reconstruire le fichier, même sans nouvelle chaîne à traduire.

Conservez la source précédente avec la cible acceptée correspondante. Si l’une ou l’autre manque, le gestionnaire traite les chaînes comme lors d’un premier passage. Le Lockfile et le cache de la CLI relient ces entrées d’une exécution à l’autre.

Choisissez le traitement des chemins protégés #

Ces options ont des effets différents sur la sortie :

OptionEffet sur la traductionEffet sur la sortie
Chemin verrouilléExclu de la traduction.Reprend la valeur de la source actuelle.
Chemin préservéExclu de la traduction.Conserve la valeur cible existante si le chemin existe ; sinon, la valeur source est conservée.
Chemin ignoréExclu de la traduction.Supprime le chemin de la cible produite.
Injection de langueLe champ de langue configuré est exclu de la traduction.Écrit la langue cible dans ce champ.

Verrouillez un identifiant partagé lorsque toutes les langues doivent utiliser la valeur source. Préservez une URL propre à la cible lorsque chaque langue possède sa propre destination. Ignorez une note réservée à la source si elle ne doit pas apparaître dans le fichier traduit. Ces choix ne sont pas de simples synonymes de « ne pas traduire ».

Pour un même chemin, le verrouillage prime sur la préservation : une valeur figurant dans les deux listes provient donc de la source. Ignorer une valeur la supprime, même si elle est aussi verrouillée, préservée ou sélectionnée pour l’injection de langue. À son emplacement, la langue injectée prime sur le verrouillage et la préservation. Privilégiez une seule règle responsable de chaque valeur et examinez la sortie lorsque des règles se chevauchent dans un objet ou un tableau.

La suppression d’un élément de tableau décale les positions des éléments suivants. Examinez le tableau obtenu comme un ensemble de données, et pas seulement comme du texte traduit. L’injection de langue peut créer les objets conteneurs manquants. Pour écrire dans un tableau, utilisez un élément existant ou la position qui suit immédiatement le dernier élément ; un chemin qui laisse des positions vides ou traverse une valeur incompatible provoque un échec.

Définissez ces options à l’aide des champs des entrées de fichier de la CLI ou des options des entrées de fichier GitHub.

Périmètre et limites de la reconstruction #

Une actualisation des clés intègre les traductions sélectionnées à la cible existante. Les valeurs cibles non sélectionnées, les clés propres à la cible et les omissions sont conservées ; les clés propres à la source qui se trouvent hors du périmètre ne sont pas ajoutées. Les écritures dans les tableaux ne doivent pas laisser de positions vides. Par exemple, sélectionner le deuxième élément d’un tableau ne permet pas de remplir automatiquement un premier élément absent. Examinez la cible dans son ensemble après une mise à jour partielle.

La sortie JSON est sérialisée avec une indentation de deux espaces et un saut de ligne final. Ne vous attendez pas à ce que les espaces ou les commentaires soient conservés à l’octet près. Pour les fichiers source contenant des commentaires, consultez JSONC et vérifiez les exigences du système qui les utilise avant de considérer un fichier réécrit comme équivalent.

Le workflow de traduction vérifie les espaces réservés pris en charge et la structure ICU, notamment les arguments modifiés ou manquants. Examinez les avertissements ou les échecs signalés, puis générez le rendu du modèle accepté avec les valeurs de l’application. Ces contrôles ne permettent pas de déterminer si le message traduit exprime bien le sens voulu.

Chargez la sortie dans l’application avec des valeurs représentatives. Vérifiez que les chemins protégés conservent les données source ou cible prévues et que le message de livraison exprime toujours la même promesse après substitution. L’analyse syntaxique vérifie la syntaxe JSON ; le rendu et la lecture permettent de vérifier le message que les utilisateurs reçoivent.