Controles de claves

La mayoría de las veces querrás traducir todas las cadenas de un archivo. Para las excepciones — nombres de marca, feature flags, textos legales o contenido interno irrelevante — la CLI ofrece tres controles por archivo, definidos dentro de una entrada files[] en .lingo/config.json.

Los tres aceptan rutas de clave en notación de punto/corchetes que reflejan la estructura del archivo:

{
  "files": [
    {
      "pattern": "content/en/app.json",
      "lockedKeys": ["meta.version"],
      "preservedKeys": ["legal.terms"],
      "ignoredKeys": ["internal.debug"]
    }
  ]
}

Bloquear — mantener el valor idéntico en todas partes#

lockedKeys copia el valor de origen en cada archivo de destino sin traducirlo. Úsalo con valores que deban mantenerse idénticos, byte por byte, en todos los idiomas:

{
  "pattern": "content/en/app.json",
  "lockedKeys": ["meta.version", "config.apiUrl"]
}

de.json y fr.json reciben meta.version con la cadena exacta del origen. Si cambias el origen, el siguiente lingo push propaga el nuevo valor a todos los idiomas, también sin traducir.

Conservar — proteger un destino escrito manualmente#

preservedKeys indica al motor que nunca sobrescriba un valor de destino que ya exista. Úsalo cuando una clave necesite traducción humana — texto legal, texto de cumplimiento o cualquier contenido que ya hayas revisado y no quieras que toque el modelo:

{
  "pattern": "content/en/settings.jsonc",
  "preservedKeys": ["featureFlags"]
}

El motor inicializa la clave a partir del origen en la primera traducción y, a partir de ahí, respeta tus cambios en cada ejecución. Compáralo con overrides más abajo.

Ignorar — eliminar la clave de la salida#

ignoredKeys elimina por completo la clave de los archivos de destino: no se traduce, no se copia y no se escribe. Úsalo con cadenas de depuración, flags internos y datos de prueba que nunca deberían llegar a una build traducida:

{
  "pattern": "content/en/app.json",
  "ignoredKeys": ["internal.debug", "dev.testData"]
}

Overrides vs. conservar#

Hay dos formas de que un valor de destino existente sobreviva a una ejecución:

• Conservar (preservedKeys) — declarativo. La clave queda protegida por configuración, en todos los idiomas, para siempre.
• Ediciones locales — lingo push compara el hash de cada destino con el lockfile. Si has editado manualmente un archivo de destino, el push lo marca como skipped (local edits) y lo deja intacto. Usa --force (con un ámbito) para sobrescribirlo. Consulta lingo push.

Usa preservedKeys cuando la protección deba ser permanente y aplicarse a todos los idiomas; deja la detección de ediciones locales para retoques manuales puntuales.

Migración desde la CLI heredada#

La CLI heredada también incluía renombrado de claves (mantener una traducción cuando cambiaba el identificador de una clave). Eso no forma parte de la CLI actual: el estado de la traducción se rastrea por hash de archivo, así que renombrar una clave hace que se vuelva a traducir en el siguiente push. Bloquear, conservar e ignorar se mantienen, con un cambio: las rutas usan notación de punto/corchetes (meta.version) en lugar de la antigua notación con barras (meta/version).