Uma cadeia de texto, por si só, é muitas vezes ambígua. "Records" pode referir-se a registos médicos, discos de música ou linhas de uma base de dados. Nos 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 do tradutor são lidas a partir de ficheiros de origem JSONC (.jsonc). Basta apontar 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 cadeia de texto 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 | informa o motor sobre a posição e a concisão esperada |
// "Light" is the theme, not weight | desambigua uma palavra com vários significados |
// Formal register | define o tom esperado |
Notas que se limitam a repetir a cadeia de texto (// This says Welcome) não acrescentam nada — pode ignorá-las.
Notas vs. configuração do motor#
As notas do tradutor aplicam-se a cada cadeia de texto e ficam no ficheiro de origem. Para regras que se aplicam a um idioma inteiro — terminologia, tom, voz da marca — defina-as antes no motor, para que se apliquem em todo o lado sem ser preciso adicionar uma nota a cada chave.
