# General Translation Changelog: gtx-cli 2.10.0: Instrucciones de traducción por clave
URL: https://generaltranslation.com/es/blog/gtx-cli_v2_10_0.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 
Authors: Fernando Aviles
Published: 2026-03-12

## 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:

```json title="translations.json"
{
  "nav": {
    "home": "Home",
    "bank": "Bank",
    "save": "Save"
  },
  "alerts": {
    "new_lead": "You have a new lead!"
  }
}
```

```json title="translations.metadata.json"
{
  "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`](/docs/cli/reference/commands/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](/docs/cli/reference/keyed-metadata).

***

## Compatibilidad con YAML

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

```yaml title="translations.metadata.yaml"
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."
```

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.