Uma string, por si só, é muitas vezes ambígua. "Records" pode referir-se a registos clínicos, discos de música ou linhas de base de dados. Em ficheiros de origem JSONC, um comentário acima de uma chave é enviado ao motor como contexto, para que traduza o significado certo:
{
// Medical context: patient medical records
"records": "Records"
}O comentário nunca aparece no resultado — serve apenas para orientar a tradução.
Onde as notas funcionam#
As notas de tradução são lidas a partir de ficheiros de origem JSONC (.jsonc). Aponte uma entrada files[] para um deles:
{ "pattern": "content/en/app.jsonc" }JSON (.json) não suporta comentários, por isso não pode incluir notas. Se quiser usar notas, use JSONC nesse ficheiro.
Vem da CLI antiga? Também lia notas dos Xcode String Catalogs (.xcstrings). Esse formato não é suportado pela CLI atual, por isso, hoje, os comentários em JSONC são a forma de associar contexto.
Como escrever notas úteis#
Uma boa nota acrescenta contexto que a própria string não transmite:
{
// 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 | Porque ajuda |
|---|---|
// Appears in the top nav | indica ao motor onde 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 apenas repetem a string (// This says Welcome) não acrescentam nada — pode saltá-las.
Notas vs. configuração do motor#
As notas de tradução aplicam-se a cada string e ficam no ficheiro de origem. Para regras que se aplicam a todo um idioma — terminologia, tom, voz da marca — defina-as antes no motor, para que sejam aplicadas em todo o lado sem precisar de uma nota em cada chave.
