Une chaîne, prise isolément, est souvent ambiguë. « Records » peut désigner des dossiers médicaux, des disques ou des enregistrements de base de données. Dans les fichiers source JSONC, un commentaire placé au-dessus d’une clé est envoyé au moteur comme contexte, afin qu’il traduise le bon sens :
{
// Medical context: patient medical records
"records": "Records"
}Le commentaire n’apparaît jamais dans le résultat — il sert uniquement à guider la traduction.
Où les notes sont prises en charge#
Les notes pour le traducteur sont lues dans les fichiers source JSONC (.jsonc). Faites pointer une entrée files[] vers l’un d’eux :
{ "pattern": "content/en/app.jsonc" }Le JSON (.json) ne permet pas les commentaires, donc impossible d’y ajouter des notes. Si vous en avez besoin, utilisez JSONC pour ce fichier.
Vous venez de l’ancien CLI ? Il lisait aussi les notes dans les catalogues de chaînes Xcode (.xcstrings). Ce format n’est pas pris en charge par le CLI actuel : aujourd’hui, les commentaires JSONC sont la bonne façon d’ajouter du contexte.
Rédiger des notes utiles#
Une bonne note apporte un contexte que la chaîne, à elle seule, ne donne pas :
{
// Button in the checkout flow — keep it short
"checkout.pay": "Pay now",
// "Set" here means a collection, not the verb
"library.set": "Set",
// Formal tone — shown in the legal footer
"footer.terms": "Terms of Service"
}| Note | Pourquoi c’est utile |
|---|---|
// Appears in the top nav | indique au moteur où la chaîne apparaît et le niveau de concision attendu |
// "Light" is the theme, not weight | lève l’ambiguïté d’un mot qui a plusieurs sens |
// Formal register | précise le ton à adopter |
Les notes qui se contentent de répéter la chaîne (// This says Welcome) n’apportent rien — inutile de les ajouter.
Notes vs. configuration du moteur#
Les notes pour le traducteur s’appliquent à chaque chaîne, directement dans votre source. Pour les règles valables à l’échelle d’une langue entière — terminologie, ton, voix de marque — définissez-les plutôt dans le moteur, afin qu’elles s’appliquent partout sans devoir ajouter une note à chaque clé.
