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 sentido correcto:
{
// Medical context: patient medical records
"records": "Records"
}El comentario nunca aparece en la salida; solo orienta la traducción.
Dónde funcionan las notas#
Las notas del traductor 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, usa JSONC para ese archivo.
¿Vienes del CLI anterior? Ese 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 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:
{
// 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 sentidos |
// 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 del traductor se definen por cadena y viven en tu 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 agregar una nota en cada clave.
