Notas para traductores

Una cadena por sí sola suele ser ambigua. "Records" podría referirse a expedientes médicos, discos de música o filas de una base de datos. En los archivos fuente JSONC, el comentario sobre una clave se envía al motor como contexto, para que traduzca el significado correcto:

jsonc

{
  // Medical context: patient medical records
  "records": "Records"
}

El comentario nunca aparece en la salida: solo guía la traducción.

Dónde funcionan las notas#

Las notas para traductores se leen de archivos fuente JSONC (.jsonc). Haz que una entrada de files[] apunte a uno de ellos:

json

{ "pattern": "content/en/app.jsonc" }

JSON (.json) no admite comentarios, así que no puede incluir notas. Si quieres usar notas, usa JSONC en ese archivo.

¿Vienes del CLI anterior? También leía notas de los Catálogos de Strings de Xcode (.xcstrings). Ese formato no es compatible con el CLI actual, así que hoy los comentarios en JSONC son la forma de adjuntar contexto.

Cómo escribir notas útiles#

Una buena nota aporta contexto que la cadena por sí sola no transmite:

jsonc

{
  // 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`	le indica al motor dónde aparece y qué tan breve debe ser
`// "Light" is the theme, not weight`	aclara una palabra con varios significados
`// Formal register`	marca la expectativa de tono

Las notas que solo repiten la cadena (// This says Welcome) no aportan nada; mejor omítelas.

Notas vs. configuración del motor#

Las notas para traductores se definen por cadena y viven en tu archivo fuente. Si necesitas reglas que se apliquen 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 agregar una nota en cada clave.