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 com o sentido correto:
{
// 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 para tradução 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, use JSONC nesse arquivo.
Vem da CLI legada? Ela também lia notas de Xcode String Catalogs (.xcstrings). Esse formato não é compatível com a CLI atual, então, hoje, a forma de adicionar contexto é com comentários em JSONC.
Como escrever notas úteis#
Uma boa nota adiciona 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 ela aparece e quão curta deve ser |
// "Light" is the theme, not weight | esclarece uma palavra com vários significados |
// Formal register | define a expectativa de tom |
Notas que apenas repetem a string (// This says Welcome) não acrescentam nada — pode pular.
Notas vs. configuração do engine#
As notas para tradução valem para cada string e ficam no seu arquivo-fonte. Já regras que se aplicam a um idioma inteiro — terminologia, tom, voz da marca — devem ser definidas no engine, para que valham em todos os lugares sem precisar de uma nota em cada chave.
