Blog

Clés de traduction qui restent cohérentes dans toute une application

Comment localize.dev nomme les clés, les réutilise pour le texte répété, sépare les textes courts et ambigus, et remarque quand le texte source change après avoir été traduit.

Stephen Ufort · 6 novembre 2026 · 3 min de lecture

La pull request du CMS Pages : 535 chaînes dans 73 fichiers déplacées vers react-i18next, avec clés et traductions

Les clés écrites à la main dérivent. Une personne écrit save_button, une autre buttons.save, une troisième common.actions.save, et trois clés contiennent le même mot. Demander à un agent de codage d'extraire des chaînes un fichier à la fois dérive de la même manière, car chaque fichier commence sans connaître les clés que les autres ont créées.

localize.dev nomme les clés pour toute l'application en une seule exécution, et s'en souvient pour la prochaine. Cet article explique comment.

Qui nomme la clé

Le modèle propose chaque clé à partir du chemin du fichier, du composant et de la chaîne. Les règles qu'il reçoit sont courtes : segments en snake case minuscules joints par des points, un espace de noms pour la fonctionnalité ou l'écran, et un nom pour ce que fait la chaîne, pas une translittération de celle-ci. src/components/AuthForm.tsx donne auth.* ; un titre devient auth.welcome_heading, pas auth.welcome_back_we_missed_you.

Tout ce qui suit est du code. Chaque clé proposée est nettoyée et enregistrée. Si deux chaînes différentes obtiennent le même nom, la seconde reçoit un suffixe _2, et une clé qui entrerait en conflit avec une branche existante du fichier de langue est renommée afin qu'aucune ne remplace l'autre.

Le même texte obtient la même clé

Avant qu'une chaîne ne soit envoyée au modèle, le moteur vérifie si ce texte a déjà une clé, soit dans votre fichier de langue source, soit à partir d'un point antérieur de la même exécution. Si c'est le cas, le code appelle à nouveau cette clé et le modèle ne voit jamais la chaîne. Une exécution signale celles-ci comme des clés réutilisées, comptant chaque endroit où le texte apparaît, donc dix boutons « Annuler » sont dix réutilisations d'une seule clé.

Textes courts qui signifient deux choses

La réutilisation par le texte seul est incorrecte pour les textes courts. « Poster » sur un bouton est un verbe, et dans le titre d'une carte, c'est un nom. De nombreuses langues utilisent des mots différents pour chacun.

Une copie de trois mots ou moins, jusqu’à 40 caractères, sans espaces réservés ni balises, a un sens à côté de son texte : l’élément et l’attribut dans lesquels il se trouve, comme button ou input[placeholder]. "Publier" sur un <button> et "Publier" dans un <h3> deviennent des messages séparés, chacun avec une indication de leur emplacement.

context sent with a string
"placeholder" attribute on <input> in component <Login>
element text inside <button> in component <Composer>

Lorsque les traductions des deux sens reviennent identiques dans toutes les langues, elles fusionnent en une seule clé. Lorsqu’elles diffèrent, les deux clés restent. Vous n’obtenez une seconde clé que si une langue en a réellement besoin.

Savoir quand le texte source a changé

Les clés ne sont utiles que si leurs traductions restent synchronisées avec la source. Lorsqu’une personne modifie "Enregistrer" en "Enregistrer les modifications" dans en.json, toutes les traductions de cette clé deviennent obsolètes, mais rien dans le fichier ne le signale.

localize.lock.json enregistre une empreinte de chaque message source au moment de sa traduction : les 12 premiers caractères hexadécimaux de son SHA-256. Validez-le avec votre code. Lors de la prochaine exécution, un message dont l’empreinte ne correspond plus sera traduit à nouveau, et localize-dev check échouera en CI avec une erreur "Traductions obsolètes" nommant les clés.

Clés dans d’autres stacks

Tous les stacks n’utilisent pas des clés pointillées. Les fichiers JSON de Laravel et les catalogues gettext utilisent le texte source comme clé, tout comme localize.dev. Les clés ARB de Flutter sont en camelCase et celles d’Android en snake_case, car ce sont leurs outils qui l’attendent.

Essayez-le sur votre propre code dans le terrain de jeu, aucun compte requis