Controles de claves

Casi siempre querrás que se traduzcan todas las cadenas de un archivo. Para las excepciones — nombres de marca, feature flags, texto legal, ruido interno — la CLI te da tres controles por archivo, definidos dentro de una entrada files[] en .lingo/config.json.

Control	Campo de configuración	Qué hace el motor
Fijar	`lockedKeys`	Copia el valor de origen en cada destino, sin traducir.
Conservar	`preservedKeys`	Mantiene lo que ya existe en el destino y nunca lo sobrescribe.
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"]
    }
  ]
}

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

lockedKeys copia el valor de origen en cada archivo de destino sin traducirlo. Úsalo para valores que deben 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 a mano#

preservedKeys le indica al motor que nunca sobrescriba un valor de destino que ya existe. Úsalo cuando una clave necesite traducción humana — texto legal, contenido de compliance, cualquier cosa que ya revisaste y no quieres que el modelo toque:

json

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

El motor inicializa la clave a partir del origen en la primera traducción y después deja intactas tus ediciones en cada ejecución posterior. Compáralo con overrides más abajo.

Ignorar — excluir la clave de la salida#

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

json

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

JSON y JSONC

Los controles de claves funcionan con 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 editaste manualmente un archivo de destino, el push lo reporta como skipped (local edits) y lo deja intacto. Pasa --force (con un alcance) para sobrescribir. Consulta lingo push.

Recurre a preservedKeys cuando la protección sea permanente y aplique a todos los idiomas; confía en la detección de ediciones locales para ajustes manuales puntuales.

Migrar desde la CLI heredada#

La CLI heredada también incluía renombrado de claves (mantener una traducción cuando cambiaba el id de una clave). Eso no forma parte de la CLI actual: el estado de traducción se rastrea por hash de archivo, así que renombrar una clave hace que se vuelva a traducir en el siguiente push. Fijar, 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).