Controles de claves

Elige si un valor procede del contenido de origen, de un destino existente, de la traducción o de los metadatos del idioma.

Algunos valores del catálogo deben ser idénticos en todos los idiomas. Otros corresponden a un destino mantenido manualmente. Los controles de claves permiten definir estas decisiones de forma explícita cuando un procesador de archivos compatible reconstruye la salida.

Son opciones de las entradas de archivo en .lingo/config.json. No seleccionan archivos ni solicitan una actualización de claves; de eso se encargan los ámbitos de traducción.

ControlComportamiento de salida
lockedKeysCopia el valor de origen sin traducirlo.
preservedKeysConserva el valor de destino existente cuando esté disponible.
ignoredKeysElimina el contenido seleccionado de la salida de un formato compatible.
injectLocaleEscribe el idioma de destino en la ubicación seleccionada.

Asigna un responsable a cada valor #

json
{
  "pattern": "locales/en.json",
  "lockedKeys": ["product.id"],
  "preservedKeys": ["legal.notice"],
  "ignoredKeys": ["internal.note"],
  "injectLocale": { "enabled": true, "key": "meta.locale" }
}

En este caso, el ID del producto procede del origen, se conserva el aviso legal existente en el destino y se omite la nota interna. La inyección del idioma escribe el idioma de destino en meta.locale y crea los objetos contenedores que falten cuando sea necesario. Para las ubicaciones en matrices, proporciona una matriz existente y selecciona un elemento existente o la posición inmediatamente posterior al final; las rutas que dejan huecos o atraviesan valores incompatibles fallan.

La conservación no puede crear una traducción humana donde no la hay. El trabajo incremental habitual ya utiliza el contenido de destino existente para conservar las modificaciones de las claves que no han cambiado; preservedKeys añade una protección explícita que va 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 solapados #

Los controles de JSON/JSONC utilizan nombres separados por puntos e índices entre corchetes, como checkout.submit o items[0].title. Una ruta protegida puede abarcar sus descendientes. Utiliza 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 una unidad, de modo que checkout/submit equivale a checkout.submit y common/error.message designa la clave error.message dentro de common. Los nombres con codificación porcentual, como legal/Terms%20of%20use, se descodifican; un patrón sin / es una ruta con puntos y no se descodifica, así que escribe un nombre codificado individual como JSONPath, por ejemplo, $['Terms of use']. Como todos los patrones con / se leen de esta forma, una clave cuyo nombre contenga / debe expresarse mediante JSONPath, por ejemplo, $.routes['/about'].title. Un * al final, como en internal/*, abarca los valores situados directamente bajo internal, pero no los objetos ni las matrices anidados allí, igual que en la CLI anterior. La CLI anterior también incluía las claves que continuaban con - o ., de modo 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 sintaxis con barras: cuando la aplicación lea la misma configuración, escribe estas listas con puntos o como JSONPath. Ámbitos describe esta sintaxis.

En una misma ubicación, una regla de exclusión elimina el valor, incluido cualquier valor de idioma inyectado. La inyección del idioma tiene prioridad sobre el bloqueo y la conservación. El bloqueo tiene prioridad sobre la conservación, por lo que una clave incluida en ambas listas utiliza su valor de origen. La exclusión de un elemento antecesor también elimina sus descendientes. Asigna un único responsable a cada valor siempre que sea posible y revisa la salida cuando las reglas se solapen en un objeto o una matriz.

Forzar el procesamiento 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 manual anterior si falta ese contexto de destino. Guarda una copia recuperable antes de forzar la sustitución.

Limitaciones de los procesadores #

JSON y JSONC admiten los cuatro controles. TypeScript, PHP, YAML y YAML con raíz por idioma admiten el bloqueo, la conservación y la omisión; stringsdict admite el bloqueo y la conservación. Los archivos de propiedades de Java admiten el bloqueo, la conservación, la omisión y el ámbito de las claves, y comparan cada patrón con la clave completa, como hacía la versión anterior de la CLI. CSV no admite ninguna de las tres reglas de claves: la CLI y la GitHub App rechazan cualquier entrada CSV que defina lockedKeys, preservedKeys o ignoredKeys. Consulta la Referencia del formato elegido para saber cómo se genera la salida.

La sintaxis abreviada de rutas admite * para segmentos completos, índices numéricos y corchetes vacíos. No admite comodines parciales. Con lingo push, las tres listas de reglas de claves también aceptan la sintaxis con barras; la GitHub App y la ubicación de inyección no la aceptan. Utiliza propiedades JSONPath entre comillas para nombres literales que contengan signos de puntuación; las consultas explícitas de $ se pasan sin cambios. La inyección requiere una única ubicación, con language como clave predeterminada cuando está activada.