# 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 --- ## Descripción general Los metadatos por clave te permiten asociar 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 fuente, con objetos de metadatos en las claves hoja. La CLI detecta automáticamente los archivos de metadatos complementarios, los valida según la estructura del archivo de origen y los envía al motor de traducción. *** ## Estructura de archivos Un archivo complementario de metadatos debe: * Estar en el mismo directorio que el archivo fuente * Seguir la convención de nomenclatura `{name}.metadata.{ext}` (p. ej., `translations.metadata.json` para `translations.json`) * Reflejar la estructura de claves del archivo fuente ``` translations.json # cadenas fuente translations.metadata.json # metadatos por clave ``` El archivo de metadatos refleja la estructura de claves de origen, pero 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": "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 } } } ``` No todas las claves necesitan metadatos: `home` no tiene ninguna entrada arriba y se traduce con normalidad. Solo proporciona entradas 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 concreta | | `maxChars` | `number` | No | Número máximo de caracteres de la salida traducida | | `sourceCode` | `Record` | No | Contexto del código fuente circundante, con la ruta del archivo como clave | *** ## Campos ### `context` Tipo: `string` 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` Tipo: `number` 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` Tipo: `Record` 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 que se está traduciendo * `after` — líneas de código fuente por debajo de la línea de destino Se admiten varias entradas por archivo si 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 {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 Funciona 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 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 de calendario." ``` *** ## Validación La CLI valida el archivo de metadatos frente a la estructura del archivo fuente. El proceso finaliza con un error si: * Una clave de metadatos no existe en el archivo fuente * Un valor de metadatos es un valor primitivo donde el archivo fuente tiene un objeto anidado * Un valor de metadatos es un array donde el archivo fuente tiene un objeto (o viceversa) * El tipo raíz (array vs. objeto) no coincide con el del archivo fuente * El archivo de metadatos no se puede analizar *** ## Compatibilidad con esquemas Los metadatos por clave funcionan con esquemas JSON (`include` y `composite`) y YAML (`include`). Los metadatos se transforman automáticamente mediante el mismo flujo de esquemas que el contenido de origen, por lo que las rutas de las claves coinciden 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 fuente correspondiente. No se traducen como archivos autónomos. Esto solo se aplica cuando el archivo fuente correspondiente existe en la lista de archivos. Un archivo `.metadata.json` sin un archivo fuente 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 modificarse.