Uma string isolada costuma ser ambígua. "Records" pode significar prontuários médicos, discos de música ou linhas de banco de dados. Em arquivos-fonte JSONC, um comentário acima de uma chave é enviado ao engine como contexto, para que ele traduza o significado certo:
{
// Medical context: patient medical records
"records": "Records"
}O comentário nunca aparece na saída — ele só orienta a tradução.
Onde as notas funcionam#
As notas do tradutor são lidas de arquivos-fonte JSONC (.jsonc). Basta apontar uma entrada files[] para um deles:
{ "pattern": "content/en/app.jsonc" }JSON (.json) não aceita comentários, então não pode incluir notas. Se você quiser usar notas, escolha JSONC para esse arquivo.
Veio da CLI legada? Ela também lia notas de Catálogos de Strings do Xcode (.xcstrings). Esse formato não é compatível com a CLI atual, então hoje os comentários em JSONC são a forma de adicionar contexto.
Como escrever notas úteis#
Uma boa nota acrescenta um contexto que a própria string não traz:
{
// 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"
}| Nota | Por que ajuda |
|---|---|
// Appears in the top nav | informa ao engine onde a string aparece e o nível de brevidade esperado |
// "Light" is the theme, not weight | desfaz a ambiguidade de uma palavra com vários significados |
// Formal register | define o tom esperado |
Notas que só repetem a string (// This says Welcome) não acrescentam nada — pode pular.
Notas vs. configuração do engine#
As notas do tradutor valem para cada string individualmente e ficam no seu arquivo-fonte. Já as regras que se aplicam a um idioma inteiro — terminologia, tom, voz da marca — devem ser definidas no engine, para valerem em todos os lugares sem precisar de uma nota em cada chave.
