Dans un vrai payload, il n’y a rarement que du texte. Le même objet qui contient un title et un body contient aussi un id, un slug, une URL de ressource, un nom de template, un code d’énumération — autant de valeurs qui identifient votre contenu ou assurent son bon fonctionnement, et qui doivent ressortir de la traduction exactement comme elles y sont entrées. Le risque est discret : donnez à un modèle un champ nommé id à côté du texte qu’il traduit, et il peut décider que "post-42" serait plus naturel localisé, ou normaliser une URL, ou « corriger » une énumération. Il suffit d’un identifiant modifié pour casser un lien ou provoquer un échec de recherche en production, dans la langue où le modèle a voulu rendre service.
lockedKeys supprime toute ambiguïté. Vous indiquez les clés qui ne doivent pas changer — par nom exact ou via un glob — et le moteur de localisation exclut ces valeurs de la traduction, puis réinjecte les valeurs source textuellement dans outputData pour chaque langue cible. Une valeur verrouillée n’est ni traduite, ni normalisée, ni réécrite. Même identifiant en entrée, même identifiant en sortie, dans chaque langue.
lockedKeys est un champ de la requête create-jobs. Voir Create jobs pour la structure complète de la requête et la réponse 202 ; cette page couvre uniquement ce qu’il faut mettre dans lockedKeys et la façon dont la correspondance fonctionne.
Verrouiller une clé par nom#
Passez lockedKeys avec votre data. Chaque entrée est un motif — dans sa forme la plus simple, le nom brut d’une clé que vous voulez préserver.
{
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"data": {
"id": "post-42",
"title": "How async APIs reduce latency",
"tags": ["performance", "infra"],
"author": { "id": "u_abc", "name": "Sam" },
"body": "Async APIs let your app stay responsive while translations process in the background."
},
"lockedKeys": ["id"]
}Le motif brut id correspond à la clé id partout où elle apparaît comme segment complet — ici, à la fois le id de premier niveau et le author.id imbriqué. Dans chaque job allemand et français, outputData conserve exactement "post-42" et "u_abc". Seuls title, name et body sont traduits ; tags reste inchangé parce qu’il ne contient aucun chemin verrouillé, et ses valeurs textuelles se traduisent comme n’importe quel autre texte.
Ce dernier point mérite d’être clarifié, car il répond à la première question que se pose un sceptique.
Une valeur verrouillée est-elle traduite ?
Non. Une clé que vous indiquez dans lockedKeys est exclue de la traduction, et sa valeur source est réinjectée textuellement dans outputData pour chaque langue cible. La valeur que vous avez envoyée revient inchangée — ni traduite, ni normalisée, ni réécrite. Le verrouillage est une garantie sur le résultat, exprimée via lockedKeys, et non un simple signal que le modèle est censé respecter.
Correspondre par nom, n’importe où — ou par position#
Un motif brut est un nom de clé, et il correspond à ce nom comme segment complet, à n’importe quelle profondeur, où que ce soit dans l’arborescence. Si audioSrc apparaît à douze endroits sous des parents différents, le motif unique audioSrc verrouille les douze. Inutile d’énumérer les chemins pour couvrir chaque occurrence — c’est le cas le plus courant, et cela tient sur une seule ligne.
Lorsque vous avez besoin d’un contrôle plus précis — verrouiller une occurrence mais pas une autre, ou chaque élément d’un tableau mais rien d’autre — utilisez un glob avec / comme séparateur de chemin. Les indices de tableau apparaissent comme des segments ordinaires, donc users/0/email et users/*/email sont tous deux des chemins valides.
| Motif | Ce qu’il verrouille |
|---|---|
audioSrc | Chaque feuille audioSrc dans l’arborescence, à n’importe quelle profondeur |
metadata | Le sous-arbre metadata entier partout où il apparaît |
metadata/author | La séquence metadata/author partout où elle apparaît, ainsi que tout ce qu’elle contient |
users/*/email | L’email de chaque utilisateur — * est un segment, et correspond à n’importe quel indice |
users/0/email | Uniquement l’e-mail du premier utilisateur |
**/{audioSrc,imageSrc} | Les deux noms de feuille via l’alternance par accolades |
Les deux motifs ci-dessus verrouillent délibérément plus qu’une seule feuille. metadata verrouille tout le sous-arbre sous cette clé — chaque valeur qu’il contient, qu’elle semble traduisible ou non, est préservée. metadata/author verrouille cette séquence partout où elle apparaît ainsi que tout ce qui se trouve en dessous. Optez pour un verrouillage de sous-arbre lorsqu’un bloc entier est structurel — un objet de configuration, un embed brut — et pour un verrouillage de feuille (metadata/author/name) lorsqu’un seul champ d’un bloc par ailleurs traduisible doit rester intact.
Glob, pas regex
* correspond exactement à un segment de chemin ; ** couvre n’importe quel nombre de segments ; {a,b} est une alternance par accolades entre plusieurs options. Il n’existe ni classes de caractères ni correspondance sur une partie de jeton — les motifs s’appliquent à des segments de chemin entiers, pas à des sous-chaînes. Écrivez users/*/email, pas une expression régulière.
Ce qui revient#
Le verrouillage modifie ce que le modèle traduit — pas la forme de votre résultat. outputData reproduit exactement la structure d’entrée : les clés verrouillées restent à leur place avec leurs valeurs d’origine, et les chaînes traduisibles autour d’elles sont traduites. Rien n’est supprimé, renommé ou réordonné.
Pour l’entrée ci-dessus, le outputData de chaque langue conserve id: "post-42" et author.id: "u_abc" inchangés, tandis que title, name et body sont dans la langue cible. La réponse complète du job — outputData, les steps par étape et le statut — est documentée dans Get a single job.
Une limite, annoncée d’emblée#
lockedKeys accepte jusqu’à 100 motifs par requête. Il s’agit d’un plafond sur le nombre de motifs, et non sur le nombre de clés auxquelles ils correspondent — un seul audioSrc ou users/*/email peut verrouiller des milliers de valeurs dans un gros payload, et compte comme un seul motif. Si vous approchez des 100 motifs distincts, c’est généralement le signe qu’un glob plus large (**/{id,slug,href}) ou un verrouillage de sous-arbre exprimera la même intention en beaucoup moins de lignes.
lockedKeys est aussi propre à chaque requête et ad hoc : il verrouille les clés pour ce groupe de jobs uniquement. Donc, pour les termes qui ne doivent jamais être traduits dans aucun job — un nom de produit, une fonctionnalité déposée, une unité qui doit rester littérale — l’endroit approprié est une entrée non traduisible dans le glossaire de votre moteur, appliquée automatiquement à chaque appel. Voir Glossaries. Utilisez lockedKeys pour les champs structurels liés à la forme d’un payload spécifique ; utilisez le glossaire pour le vocabulaire constant dans l’ensemble de votre contenu.
