# gt: General Translation CLI tool: Metadatos por clave
URL: https://generaltranslation.com/es/docs/cli/reference/keyed-metadata.mdx
---

title: Metadatos por clave
description: Adjunta instrucciones de traducción por clave a archivos JSON y YAML de General Translation. Referencia de la API para metadatos por clave.

---

Proporcionas un archivo complementario de metadatos que refleja la estructura de claves del archivo fuente, con un objeto de metadatos en cada nodo hoja. Cada objeto contiene instrucciones para traducir esa clave en particular.

La CLI detecta automáticamente los archivos de metadatos complementarios, los valida con la estructura de claves del archivo fuente y los envía al motor de traducción.

## Campos [#fields]

| Campo                        | Descripción                                                             | Tipo     | Opcional | Predeterminado |
| ---------------------------- | ----------------------------------------------------------------------- | -------- | -------- | -------------- |
| [`context`](#context)        | Instrucciones de traducción para una cadena específica.                 | `string` | Sí       | —              |
| [`maxChars`](#max-chars)     | Número máximo de caracteres de la salida traducida.                     | `number` | Sí       | —              |
| [`sourceCode`](#source-code) | Contexto del código fuente circundante, organizado por ruta de archivo. | `object` | Sí       | —              |

## Estructura de archivos [#structure]

Un archivo complementario de metadatos debe estar en el mismo directorio que el archivo fuente, seguir la convención de nomenclatura `{name}.metadata.{ext}` y reflejar la estructura de claves del archivo fuente con un objeto de metadatos en cada nodo hoja.

```text
translations.json           # cadenas fuente
translations.metadata.json  # metadatos por clave
```

Solo proporciona entradas para las claves que necesiten instrucciones. Las claves sin entrada se traducen normalmente.

```json title="translations.json"
{
  "nav": {
    "home": "Home",
    "bank": "Bank",
    "save": "Save"
  }
}
```

```json title="translations.metadata.json"
{
  "nav": {
    "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
    }
  }
}
```

## `context` [#context]

**Tipo** `string` · **Opcional** · **Predeterminado** —

Instrucciones de traducción que se aplican a una cadena concreta. Úsalo para desambiguar palabras con varios significados, especificar terminología del dominio o aclarar la interpretación deseada.

```json
{
  "bank": {
    "context": "Riverbank. The side of a river where land meets water, NOT a financial institution."
  }
}
```

## `maxChars` [#max-chars]

**Tipo** `number` · **Opcional** · **Predeterminado** —

Un límite máximo de caracteres en la salida traducida. El motor usará sinónimos más cortos, abreviaturas o una redacción concisa para ajustarse a ese límite. Se aplica según las posibilidades: si el límite no es viable para el contenido de origen, se devuelve la traducción completa.

```json
{
  "save": {
    "maxChars": 10
  }
}
```

## `sourceCode` [#source-code]

**Tipo** `object` · **Opcional** · **Predeterminado** —

Contexto del código fuente alrededor de una cadena. Se organiza por ruta de archivo y cada entrada contiene `before` (líneas de código fuente por encima de la línea de destino), `target` (la línea que contiene la cadena) y `after` (líneas de código fuente por debajo). Se admiten varias entradas por archivo cuando la misma cadena aparece en distintas ubicaciones.

```json
{
  "new_lead": {
    "sourceCode": {
      "components/Dashboard.tsx": [
        {
          "before": "function NotificationBanner({ type }) {\n  const gt = useGT();",
          "target": "  const msg = gt('You have a new lead!');",
          "after": "  return <Banner variant=\"success\">{msg}</Banner>;\n}"
        }
      ]
    }
  }
}
```

### Ejemplo combinado

Los tres campos en una misma clave:

```json
{
  "save_button": {
    "context": "Sports term. A goalkeeper's save — preventing a goal from being scored. NOT saving data.",
    "maxChars": 12,
    "sourceCode": {
      "components/MatchStats.tsx": [
        {
          "before": "const stats = useMatchStats();\nconst gt = useGT();",
          "target": "const label = gt('Save');",
          "after": "return <StatBadge icon={<GoalkeeperIcon />}>{label}: {stats.saves}</StatBadge>;"
        }
      ]
    }
  }
}
```

## YAML [#yaml]

Los metadatos funcionan igual con los archivos complementarios `.metadata.yaml` o `.metadata.yml`.

```yaml title="translations.metadata.yaml"
ui:
  buttons:
    save:
      context: "Término deportivo. La parada de un portero, NO guardar datos."
      maxChars: 12
  labels:
    date:
      context: "El fruto comestible de la palmera datilera. NO una fecha de calendario."
```

## Validación [#validation]

La CLI valida el archivo de metadatos con respecto a la estructura de claves del archivo fuente y termina con un error si una clave de metadatos no existe en el origen, si un tipo de valor no coincide con el del origen (primitivo vs. objeto, lista vs. objeto), si el tipo raíz no coincide o si el archivo no se puede analizar.

## Esquema y correspondencia [#schema]

El metadato por clave funciona con esquemas JSON (`include` y `composite`) y esquemas YAML (`include`); los metadatos se transforman a través del mismo flujo de esquemas para que las rutas de las claves coincidan durante la traducción. Los archivos complementarios se emparejan con su archivo fuente y no se traducen por sí solos: un archivo `.metadata.json` sin un archivo fuente correspondiente se trata como un archivo normal. Cambiar solo los metadatos no activa una nueva traducción; el contenido fuente también debe cambiar.