Una cadena, por sí sola, suele ser ambigua. "Records" puede significar historiales médicos, discos o filas de una base de datos. En los archivos fuente JSONC, el comentario que va sobre una clave se envía al motor como contexto, para que traduzca el sentido correcto:
{
// Medical context: patient medical records
"records": "Records"
}El comentario nunca aparece en el resultado: solo guía la traducción.
Dónde funcionan las notas#
Las notas de traducción se leen de archivos fuente JSONC (.jsonc). Haz que una entrada de files[] apunte a uno de ellos:
{ "pattern": "content/en/app.jsonc" }JSON (.json) no admite comentarios, así que no puede incluir notas. Si quieres usar notas, utiliza JSONC en ese archivo.
¿Vienes del CLI heredado? También leía notas de los catálogos de cadenas de Xcode (.xcstrings). Ese formato no es compatible con el CLI actual, así que hoy por hoy la forma de añadir contexto es mediante comentarios en JSONC.
Cómo escribir notas útiles#
Una buena nota aporta contexto que la propia cadena no deja claro:
{
// 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 qué ayuda |
|---|---|
// Appears in the top nav | indica al motor dónde aparece y la concisión esperada |
// "Light" is the theme, not weight | desambigua una palabra con varios significados |
// Formal register | marca las expectativas de tono |
Las notas que se limitan a repetir la cadena (// This says Welcome) no aportan nada; mejor omítelas.
Notas vs. configuración del motor#
Las notas de traducción se aplican a cada cadena y van en el archivo fuente. Si hay reglas que deben aplicarse a todo un idioma —terminología, tono, voz de marca—, configúralas en el motor, para que se apliquen en todas partes sin tener que añadir una nota en cada clave.
