Contrôle des clés

La plupart du temps, vous voulez traduire toutes les chaînes d’un fichier. Mais pour les exceptions — noms de marque, feature flags, textes juridiques, contenu interne sans intérêt — le CLI propose trois contrôles par fichier, à définir dans une entrée files[] de .lingo/config.json.

Ces trois options acceptent des chemins de clés en notation point/crochets qui reflètent la structure du fichier :

{
  "files": [
    {
      "pattern": "content/en/app.json",
      "lockedKeys": ["meta.version"],
      "preservedKeys": ["legal.terms"],
      "ignoredKeys": ["internal.debug"]
    }
  ]
}

Lock — garder la même valeur partout#

lockedKeys copie la valeur source dans chaque fichier cible sans la traduire. Utilisez-le pour les valeurs qui doivent rester strictement identiques d’une langue à l’autre :

{
  "pattern": "content/en/app.json",
  "lockedKeys": ["meta.version", "config.apiUrl"]
}

de.json et fr.json reçoivent meta.version avec la chaîne source exacte. Modifiez la source, et le prochain lingo push propage la nouvelle valeur à chaque langue, toujours sans la traduire.

Preserve — protéger une cible rédigée à la main#

preservedKeys indique au moteur de ne jamais écraser une valeur cible déjà existante. Utilisez-le lorsqu’une clé doit être traduite par un humain — texte juridique, contenu de conformité, ou tout texte que vous avez validé et que vous ne voulez pas voir modifié par le modèle :

{
  "pattern": "content/en/settings.jsonc",
  "preservedKeys": ["featureFlags"]
}

Le moteur initialise la clé à partir de la source lors de la première traduction, puis laisse vos modifications intactes à chaque exécution suivante. Comparez avec overrides ci-dessous.

Ignore — retirer la clé de la sortie#

ignoredKeys supprime complètement la clé des fichiers cibles — elle n’est ni traduite, ni copiée, ni écrite. Utilisez-le pour les chaînes de débogage, les indicateurs internes et les données de test qui ne doivent jamais se retrouver dans une build traduite :

{
  "pattern": "content/en/app.json",
  "ignoredKeys": ["internal.debug", "dev.testData"]
}

Overrides vs. preserve#

Une valeur cible existante peut survivre à une exécution de deux façons :

• Preserve (preservedKeys) — déclaratif. La clé est protégée par la configuration, dans chaque langue, durablement.
• Modifications locales — lingo push compare le hash de chaque cible au lockfile. Si vous avez modifié manuellement un fichier cible, le push le signale comme skipped (local edits) et n’y touche pas. Passez --force (avec une portée) pour l’écraser. Voir lingo push.

Privilégiez preservedKeys lorsque la protection doit être permanente et s’appliquer à toutes les langues ; fiez-vous à la détection des modifications locales pour des retouches manuelles ponctuelles.

Migrer depuis l’ancien CLI#

L’ancien CLI prenait aussi en charge le renommage de clés (conserver une traduction quand l’identifiant d’une clé changeait). Ce n’est plus le cas dans le CLI actuel — l’état de traduction est suivi par hash de fichier, donc renommer une clé entraîne sa retraduction au prochain push. Lock, preserve et ignore restent pris en charge, avec une différence : les chemins utilisent la notation point/crochets (meta.version) au lieu de l’ancienne notation à barres obliques (meta/version).