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.

Control	Campo de configuración	Qué hace el motor
Bloquear	`lockedKeys`	Copia el valor de origen en todos los destinos, sin traducirlo.
Conservar	`preservedKeys`	Mantiene lo que ya existe en el destino y no lo sobrescribe nunca.
Ignorar	`ignoredKeys`	Omite por completo la clave del archivo de destino.

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

json

{
  "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:

json

{
  "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:

json

{
  "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:

json

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

JSON y JSONC

Los controles de claves funcionan sobre formatos estructurados de clave/valor — json y jsonc. En los formatos de la familia Markdown, delimita la traducción con translateFrontmatterFields y translateComponentProps en su lugar (consulta Formats).

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).