Controles de claves
Elige si un valor proviene del contenido de origen, de un destino existente, de una traducción o de los metadatos del idioma.
Algunos valores del catálogo deben mantenerse idénticos en todos los idiomas. Otros corresponden a un destino que se mantiene manualmente. Los controles de claves permiten definir estas decisiones de forma explícita cuando un procesador de archivos compatible reconstruye la salida.
Estas opciones se configuran en las entradas de archivos de .lingo/config.json. No seleccionan archivos ni solicitan una actualización de claves; de eso se encargan los ámbitos de traducción.
| Control | Comportamiento de salida |
|---|---|
lockedKeys | Copia el valor de origen sin traducirlo. |
preservedKeys | Conserva el valor de destino existente cuando está disponible. |
ignoredKeys | Elimina el contenido seleccionado de la salida de un formato compatible. |
injectLocale | Escribe el idioma de destino en la ubicación seleccionada. |
Asigna un responsable a cada valor #
{
"pattern": "locales/en.json",
"lockedKeys": ["product.id"],
"preservedKeys": ["legal.notice"],
"ignoredKeys": ["internal.note"],
"injectLocale": { "enabled": true, "key": "meta.locale" }
}Aquí, el ID del producto proviene del origen, se conserva el aviso legal existente en el destino y se omite la nota interna. La inyección de idioma escribe el idioma de destino en meta.locale y crea los objetos contenedores que falten cuando sea necesario. Para las ubicaciones en arreglos, proporciona un arreglo existente y selecciona un elemento existente o la posición inmediatamente posterior al último elemento; las rutas que dejan huecos o atraviesan valores incompatibles fallan.
La conservación no puede crear una traducción humana donde no existe ninguna. El trabajo incremental habitual ya usa el contenido de destino existente para conservar las ediciones en claves que no han cambiado; preservedKeys agrega una protección explícita más allá de ese comportamiento. Un cambio en el origen o en el nombre de una clave JSON puede seguir requiriendo trabajo adicional.
Rutas y controles superpuestos #
Los controles de JSON/JSONC usan nombres separados por puntos e índices entre corchetes, como checkout.submit o items[0].title. Una ruta protegida puede abarcar sus descendientes. Usa una propiedad JSONPath entre comillas, como $['checkout.submit'], cuando una clave literal contenga un punto. lingo push también lee listas escritas para la CLI anterior con /: cada nombre entre / se interpreta como un nombre completo, de modo que checkout/submit equivale a checkout.submit y common/error.message identifica la clave error.message dentro de common. Los nombres con codificación porcentual, como legal/Terms%20of%20use, se decodifican; un patrón sin / es una ruta con puntos y no se decodifica, así que escribe un nombre codificado individual como JSONPath, por ejemplo, $['Terms of use']. Como todos los patrones con / se leen de esta manera, una clave cuyo nombre contenga / requiere JSONPath, como $.routes['/about'].title. Un * al final, como en internal/*, abarca los valores directamente dentro de internal, pero no los objetos ni los arreglos anidados allí, al igual que en la CLI anterior. La CLI anterior también encontraba coincidencias con claves que continuaban con - o ., por lo que legal/terms abarcaba legal/terms-short. Esa coincidencia por prefijo ya no se aplica; enumera esas claves por separado. La GitHub App no acepta la forma con barras: cuando la aplicación lea la misma configuración, escribe estas listas con puntos o como JSONPath. Ámbitos describe esta forma.
En una misma ubicación, una regla de omisión elimina el valor, incluso si es un valor de idioma inyectado. La inyección de idioma tiene prioridad sobre el bloqueo y la conservación. El bloqueo tiene prioridad sobre la conservación, por lo que una clave presente en ambas listas usa su valor de origen. Si se omite un elemento antecesor, también se eliminan sus descendientes. Siempre que sea posible, asigna un único responsable a cada valor y revisa la salida cuando las reglas se superpongan en un objeto o arreglo.
El reemplazo forzado de todo el archivo elimina el artefacto del destino actual que se envía al servidor. Una regla de conservación no puede mantener la redacción humana anterior si falta ese contexto de destino. Guarda una copia recuperable antes de forzar el reemplazo.
Limitaciones de los procesadores #
JSON y JSONC admiten los cuatro controles. TypeScript, PHP, YAML y YAML con raíz por idioma admiten bloqueo, preservación y omisión; stringsdict admite bloqueo y preservación. Las propiedades de Java admiten bloqueo, preservación, omisión y alcance de claves, y comparan cada patrón con la clave completa, tal como lo hacía la CLI anterior. CSV no admite ninguna de las tres reglas de claves: la CLI y la GitHub App rechazan cualquier entrada CSV que configure lockedKeys, preservedKeys o ignoredKeys. Consulta la Referencia del formato elegido para conocer cómo maneja la salida.
La forma abreviada de las rutas admite * para segmentos completos, índices numéricos y corchetes vacíos. Rechaza los comodines parciales. Con lingo push, las tres listas de reglas de claves también aceptan la forma con barras; la GitHub App y la ubicación de inyección no la aceptan. Usa propiedades JSONPath entre comillas para nombres literales que contengan signos de puntuación; las consultas explícitas $ se pasan sin cambios. La inyección requiere una única ubicación y, cuando está habilitada, usa language como clave predeterminada.