Contrôles des clés

Choisissez si une valeur doit provenir du contenu source, d’une cible existante, de la traduction ou des métadonnées de langue.

Certaines valeurs du catalogue doivent rester identiques dans toutes les langues. D’autres relèvent d’une cible mise à jour manuellement. Les contrôles des clés explicitent ces choix lorsqu’un gestionnaire de fichiers compatible reconstruit la sortie.

Ces options se définissent pour chaque entrée de fichier dans .lingo/config.json. Elles ne sélectionnent pas les fichiers et ne demandent pas d’actualisation des clés ; ce sont les périmètres de traduction qui s’en chargent.

ContrôleComportement en sortie
lockedKeysCopier la valeur source sans la traduire.
preservedKeysConserver la valeur cible existante lorsqu’elle est disponible.
ignoredKeysSupprimer le contenu sélectionné de la sortie d’un format compatible.
injectLocaleÉcrire la langue cible à l’emplacement sélectionné.

Attribuez un responsable à chaque valeur #

json
{
  "pattern": "locales/en.json",
  "lockedKeys": ["product.id"],
  "preservedKeys": ["legal.notice"],
  "ignoredKeys": ["internal.note"],
  "injectLocale": { "enabled": true, "key": "meta.locale" }
}

Ici, l’identifiant du produit provient de la source, la mention légale existante dans la cible est conservée et la note interne est omise. L’injection de langue écrit la langue cible dans meta.locale et crée les objets conteneurs manquants si nécessaire. Pour un emplacement dans un tableau, fournissez un tableau existant et sélectionnez un élément existant ou la position immédiatement après le dernier élément ; les chemins qui créent des trous ou traversent des valeurs incompatibles échouent.

La conservation ne peut pas créer une traduction humaine là où il n’en existe aucune. Le traitement incrémental habituel utilise déjà le contenu cible existant pour conserver les modifications apportées aux clés inchangées ; preservedKeys ajoute une protection explicite au-delà de ce comportement. Une modification de la source ou le renommage d’une clé JSON peut tout de même nécessiter un nouveau traitement.

Chemins et chevauchement des contrôles #

Les contrôles JSON/JSONC utilisent des noms séparés par des points et des indices entre crochets, comme checkout.submit ou items[0].title. Un chemin protégé peut couvrir ses descendants. Utilisez une propriété JSONPath entre guillemets, comme $['checkout.submit'], lorsqu’une clé littérale contient un point. lingo push lit aussi les listes écrites pour l’ancienne CLI avec / : chaque nom entre / est interprété comme un tout, donc checkout/submit équivaut à checkout.submit et common/error.message désigne la clé error.message sous common. Les noms encodés en pourcentage, comme legal/Terms%20of%20use, sont décodés ; un motif sans / est un chemin à points et n’est pas décodé. Écrivez donc un nom encodé unique sous forme de JSONPath, comme $['Terms of use']. Puisque chaque motif contenant / est lu de cette manière, une clé dont le nom contient / nécessite JSONPath, comme $.routes['/about'].title. Un * final, comme dans internal/*, couvre les valeurs directement sous internal, mais pas les objets ou tableaux qui y sont imbriqués, comme dans l’ancienne CLI. L’ancienne CLI reconnaissait aussi les clés dont le nom se prolonge par - ou . : legal/terms couvrait ainsi legal/terms-short. Cette correspondance par préfixe n’existe plus ; listez ces clés séparément. La GitHub App n’accepte pas la forme avec des barres obliques : lorsqu’elle lit la même configuration, écrivez ces listes avec des points ou sous forme de JSONPath. Périmètres décrit cette forme.

À un même emplacement, une règle d’exclusion supprime la valeur, même s’il s’agit d’une valeur de langue injectée. L’injection de langue est prioritaire sur le verrouillage et la conservation. Le verrouillage est prioritaire sur la conservation : une clé présente dans les deux listes utilise donc sa valeur source. L’exclusion d’un ancêtre supprime aussi ses descendants. Attribuez si possible un seul responsable à chaque valeur et vérifiez la sortie lorsque des règles se chevauchent au sein d’un objet ou d’un tableau.

Le remplacement forcé d’un fichier entier efface l’artefact de la cible actuelle envoyé au serveur. Une règle de conservation ne peut pas préserver une formulation humaine antérieure en l’absence de ce contexte cible. Gardez une copie récupérable avant tout remplacement forcé.

Limites des gestionnaires #

JSON et JSONC prennent en charge les quatre contrôles. TypeScript, PHP, YAML et YAML avec une langue à la racine prennent en charge le verrouillage, la préservation et l’exclusion ; stringsdict prend en charge le verrouillage et la préservation. Les fichiers de propriétés Java prennent en charge le verrouillage, la préservation, l’exclusion et la portée des clés : chaque motif est comparé à la clé entière, comme dans la version précédente de la CLI. CSV ne prend en charge aucune des trois règles de clés : la CLI et la GitHub App rejettent toute entrée CSV qui définit lockedKeys, preservedKeys ou ignoredKeys. Consultez la référence du format choisi pour connaître son comportement en sortie.

La forme courte des chemins prend en charge * sur un segment entier, les indices numériques et les crochets vides. Elle rejette les caractères génériques partiels. Avec lingo push, les trois listes de règles de clé acceptent aussi la forme avec des barres obliques ; ni la GitHub App ni l’emplacement d’injection ne l’acceptent. Utilisez des propriétés JSONPath entre guillemets pour les noms littéraux contenant des signes de ponctuation ; les requêtes $ explicites sont transmises telles quelles. L’injection nécessite un seul emplacement, avec language comme clé activée par défaut.