Una cadena por sí sola suele ser ambigua. "Records" puede significar historiales médicos, discos de música o filas de una base de datos. En los archivos fuente JSONC, un comentario sobre una clave se envía al motor como contexto, para que traduzca el significado correcto:
{
// 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:
{ "pattern": "content/en/app.jsonc" }JSON (.json) no admite comentarios, así que no puede incluir notas. Si quieres añadir notas, usa JSONC para 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 los comentarios en JSONC son la forma de añadir contexto.
Cómo escribir notas útiles#
Una buena nota aporta contexto que la propia cadena no da:
{
// 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 lo breve que debe ser |
// "Light" is the theme, not weight | aclara una palabra con varios significados |
// Formal register | marca el tono esperado |
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 son específicas de cada cadena y van en el archivo fuente. Para reglas que se aplican 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.
