A string on its own is often ambiguous. "Records" could mean medical records, music records, or database rows. In JSONC source files, a comment above a key is sent to the engine as context, so it translates the right meaning:
{
// Medical context: patient medical records
"records": "Records"
}The comment never appears in the output — it only steers the translation.
Where notes work#
Translator notes are read from JSONC (.jsonc) source files. Point a files[] entry at one:
{ "pattern": "content/en/app.jsonc" }JSON (.json) has no comments, so it can't carry notes. If you want notes, use JSONC for that file.
Coming from the legacy CLI? It also read notes from Xcode String Catalogs (.xcstrings). That format isn't supported by the current CLI, so JSONC comments are the way to attach context today.
Writing useful notes#
A good note adds context the string itself doesn't carry:
{
// 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 | Why it helps |
|---|---|
// Appears in the top nav | tells the engine about placement and expected brevity |
// "Light" is the theme, not weight | disambiguates a word with several meanings |
// Formal register | sets tone expectations |
Notes that just restate the string (// This says Welcome) add nothing — skip them.
Notes vs. engine config#
Translator notes are per-string, in your source. For rules that apply across a whole locale — terminology, tone, brand voice — encode them in the engine instead, so they apply everywhere without a note on every key.
