# gt: General Translation CLI tool: Metadatos por clave
URL: https://generaltranslation.com/es/docs/cli/reference/keyed-metadata.mdx
Docs index: https://generaltranslation.com/llms.txt
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 concreta. | `string` | Sí | — |
| [`maxChars`](#max-chars) | Longitud máxima solicitada para las traducciones generadas. | `integer` | 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** `integer` · **Opcional** · **Predeterminado** —
Un conteo máximo de caracteres como entero positivo solicitado al motor de traducción. 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 fuente, se devuelve la traducción completa. Se ignoran los valores cero, negativos y fraccionarios.
```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.
El servicio de traducción utiliza como máximo cinco entradas por archivo. Trunca cada valor de `before` y `after` a 2.000 caracteres y cada valor de `target` a 500 caracteres.
```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 {msg};\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 }>{label}: {stats.saves};"
}
]
}
}
}
```
## 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.
La CLI no rechaza valores numéricos de `maxChars` no válidos. El motor de traducción aplica únicamente enteros positivos y trata los demás números como si no se hubiera establecido ningún límite.
## 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.
## Sitemap
See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.