Resumen

gtx-cli 2.10.0 añade compatibilidad con metadatos por clave en archivos de traducción JSON y YAML. Son instrucciones de traducción por clave que te permiten controlar con precisión cómo se traduce cada cadena individual.

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

Así se ve

Creas un archivo de metadatos complementario que se coloca junto a tu archivo fuente y refleja la estructura de sus claves. En el nivel más específico, 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": "Baseball term — home plate on a diamond. NOT a house."
    },
    "bank": {
      "context": "Riverbank — the side of a river. NOT a financial institution."
    },
    "save": {
      "context": "Sports term — a goalkeeper preventing a goal. NOT saving data.",
      "maxChars": 12
    }
  },
  "alerts": {
    "new_lead": {
      "context": "Sales/CRM context. A 'lead' is a potential customer.",
      "maxChars": 30
    }
  }
}

El archivo complementario debe estar en el mismo directorio que el archivo fuente y seguir la convención de nombres {name}.metadata.json (o .metadata.yaml para archivos YAML). El 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 de "Banco" (institución financiera), y "Save" pasa a ser "Parada" (atajada de un portero) en lugar de "Guardar" (almacenar). Para las cadenas que ya son inequívocas, no necesitas proporcionar metadatos; añade entradas solo para las claves que se beneficien de ello.

Campos admitidos

Actualmente admitimos tres campos de metadatos:

• context — instrucciones de traducción para una cadena específica. Este es el campo más importante: úsalo para desambiguar palabras, especificar terminología del dominio o aclarar la intención.
• maxChars — un límite máximo de caracteres en la salida traducida. Se aplica en la medida de lo posible: el motor usará sinónimos más breves y una redacción concisa para ajustarse, pero no truncará una traducción hasta dejarla en una longitud inviable.
• sourceCode — contexto del código fuente que rodea a 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 información completa y ejemplos de cada campo, consulta la referencia de metadatos por clave.

Compatibilidad con YAML

El mismo enfoque funciona con 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 del calendario."
    chips:
      context: "Inglés británico: tiras de patata frita caliente (papas fritas). NO patatas fritas de bolsa ni microchips."