# gt: General Translation CLI tool: Metadatos por clave URL: https://generaltranslation.com/es/docs/cli/reference/keyed-metadata.mdx --- title: Metadatos por clave description: Metadatos de traducción por clave para archivos JSON y YAML --- ## Resumen Los metadatos por clave te permiten adjuntar instrucciones de traducción a claves individuales en tus archivos JSON y YAML. Proporcionas un archivo complementario `.metadata.json` o `.metadata.yaml` que refleja la estructura de claves del archivo de origen, con objetos de metadatos en los nodos hoja. La CLI detecta automáticamente los archivos de metadatos complementarios, los valida con la estructura del archivo de origen y los envía al motor de traducción. *** ## Estructura del archivo Un archivo de metadatos complementario debe: * Estar en el mismo directorio que el archivo de origen * Seguir la convención de nombres `{name}.metadata.{ext}` (p. ej., `translations.metadata.json` para `translations.json`) * Reflejar la estructura de claves del archivo de origen ``` translations.json # cadenas de origen translations.metadata.json # metadatos por clave ``` El archivo de metadatos refleja la estructura de claves de origen, con objetos de metadatos en los nodos hoja en lugar de cadenas: ```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": { "bank": { "context": "Ribera — la orilla de un río. NO una institución financiera." }, "save": { "context": "Término deportivo — un portero que detiene un gol. NO guardar datos.", "maxChars": 12 } }, "alerts": { "new_lead": { "context": "Contexto de ventas/CRM. Un 'lead' es un cliente potencial.", "maxChars": 30 } } } ``` No todas las claves necesitan metadatos: `home` no tiene ninguna entrada más arriba y se traduce con normalidad. Proporciona entradas solo para las claves que necesiten instrucciones de traducción específicas. *** ## Referencia de campos | Campo | Tipo | Obligatorio | Descripción | | ------------ | --------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------ | | `context` | `string` | No | Instrucciones de traducción para esta cadena específica | | `maxChars` | `number` | No | Número máximo de caracteres para la salida traducida | | `sourceCode` | `Record` | No | contexto del código de origen circundante, indexado por la ruta del archivo | *** ## Campos ### `context` Tipo: `string` Instrucciones de traducción aplicadas a una cadena específica. Ú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` Type: `number` Un límite máximo de caracteres para la salida traducida. El motor usará sinónimos más cortos, abreviaturas o una redacción más concisa para ajustarse al límite. Se aplica en la medida de lo posible. Si el límite no es viable para el contenido de origen, se devuelve la traducción completa. ```json { "save": { "maxChars": 10 } } ``` ### `sourceCode` Tipo: `Record` Contexto del código de origen que rodea una cadena. Se indexa por ruta de archivo, y cada entrada contiene: * `before` — líneas de código de origen por encima de la línea de destino * `target` — la línea que contiene la cadena que se está traduciendo * `after` — líneas de código de origen por debajo de la línea de destino Se admiten varias entradas por archivo si la misma cadena aparece en ubicaciones diferentes. ```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 sola 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 Funciona igual con los archivos complementarios `.metadata.yaml` o `.metadata.yml`: ```yaml title="translations.metadata.yaml" ui: buttons: save: context: "Sports term. A goalkeeper's save, NOT saving data." maxChars: 12 draft: context: "Beer on tap, as in 'draft beer'. NOT a document version." labels: date: context: "The edible fruit of the date palm. NOT a calendar date." ``` *** ## Validación La CLI valida el archivo de metadatos según la estructura del archivo de origen. El proceso finaliza con un error si: * Una clave de metadatos no existe en el archivo de origen * Un valor de metadatos es un tipo primitivo donde el archivo de origen tiene un objeto anidado * Un valor de metadatos es un array donde el archivo de origen tiene un objeto (o viceversa) * El tipo raíz (array frente a objeto) no coincide con el archivo de origen * El archivo de metadatos no se puede parsear *** ## Compatibilidad con esquemas Los metadatos por clave funcionan con esquemas JSON (`include` y `composite`) y con esquemas YAML (`include`). Los metadatos se transforman automáticamente mediante el mismo flujo de procesamiento de esquemas que el contenido de origen, por lo que las rutas de las claves quedan alineadas en el momento de la traducción, independientemente de la estructura del archivo. *** ## Filtrado de archivos complementarios Los archivos de metadatos complementarios se asocian automáticamente con el archivo de origen correspondiente. No se traducen como archivos independientes. Esto solo se aplica cuando el archivo de origen correspondiente está en la lista de archivos. Un archivo `.metadata.json` sin un archivo de origen correspondiente se trata como un archivo normal. *** ## Comportamiento de la retraducción Los cambios realizados únicamente en el archivo de metadatos no activan la retraducción si el contenido de origen no ha cambiado. Para aplicar los metadatos actualizados, el contenido de origen también debe cambiar.