Resumen

gtx-cli 2.10.0 añade soporte para metadatos por clave en archivos de traducción JSON y YAML. Se trata de instrucciones de traducción por clave que te dan un control preciso sobre cómo se traducen las cadenas individuales.

Hasta ahora, el contexto de traducción para archivos con claves funcionaba a nivel de proyecto. Los controles de estilo, las entradas del glosario y las reglas específicas de la configuración regional se aplicaban de forma general a todo tu contenido. Los metadatos por clave te permiten ir un nivel más allá y asociar indicaciones de traducción específicas directamente a claves individuales en tus archivos.

Así se ve

Creas un archivo de metadatos complementario ubicado junto a tu archivo fuente y que refleja la estructura de sus claves. En los nodos hoja, en lugar de cadenas, proporcionas objetos de metadatos con instrucciones de traducción:

{
  "nav": {
    "home": "Home",
    "bank": "Bank",
    "save": "Save"
  },
  "alerts": {
    "new_lead": "You have a new lead!"
  }
}

{
  "nav": {
    "home": {
      "context": "Término de béisbol — home plate en un diamante. NO una casa."
    },
    "bank": {
      "context": "Ribera — la orilla de un río. NO una institución financiera."
    },
    "save": {
      "context": "Término deportivo — un portero que evita un gol. NO guardar datos.",
      "maxChars": 12
    }
  },
  "alerts": {
    "new_lead": {
      "context": "Contexto de ventas/CRM. Un 'lead' es un cliente potencial.",
      "maxChars": 30
    }
  }
}

El archivo complementario debe estar en el mismo directorio que el archivo fuente y seguir la convención de nomenclatura {name}.metadata.json (o .metadata.yaml para archivos YAML). La CLI lo detecta automáticamente cuando ejecutas npx gt translate.

Con contexto por clave, "Bank" se traduce como "Ribera" (orilla de un río) en lugar del posible "Banco" (institución financiera), y "Save" pasa a ser "Parada" (atajada del portero) en lugar de "Guardar" (almacenar). Para las cadenas que ya no son ambiguas, no necesitas proporcionar metadatos; añade entradas solo para las claves que se beneficien de ello.

Campos con soporte

Actualmente ofrecemos soporte para tres campos de metadatos:

• context — instrucciones de traducción para una cadena concreta. Este es el campo más importante: úsalo para desambiguar palabras, especificar la terminología del dominio o aclarar la intención.
• maxChars — un límite máximo de caracteres en la traducción generada. Se aplica en la medida de lo posible: el motor usará sinónimos más cortos y frases concisas para ajustarse, pero no truncará una traducción hasta dejarla en una longitud inviable.
• sourceCode — contexto del código fuente circundante de una cadena. Te permite mostrarle al motor dónde y cómo se usa la cadena en tu base de código, lo que le ayuda a tomar mejores decisiones sobre el tono, la terminología y la redacción.

Todos los campos son opcionales para cada clave. Para ver todos los detalles y ejemplos de cada campo, consulta la referencia de metadatos por clave.

Soporte para YAML

El mismo enfoque funciona para archivos YAML. Crea un archivo complementario .metadata.yaml con la misma estructura de claves:

ui:
  buttons:
    save:
      context: "Término deportivo — la parada de un portero. NO guardar datos."
    draft:
      context: "Cerveza de barril, como en 'draft beer'. NO una versión de documento."
  labels:
    date:
      context: "El fruto comestible de la palmera datilera. NO una fecha de calendario."
    chips:
      context: "Inglés británico: patatas fritas calientes en tiras (papas fritas). NO patatas fritas de bolsa ni microchips."