Controles de chave

Na maioria dos casos, você vai querer traduzir todas as strings de um arquivo. Para as exceções — nomes de marca, feature flags, textos legais, ruído interno — a CLI oferece três controles por arquivo, definidos em uma entrada files[] dentro de .lingo/config.json.

Os três aceitam caminhos de chave em notação de ponto/colchetes, espelhando a estrutura do arquivo:

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

Fixar — manter o valor idêntico em todos os lugares#

lockedKeys copia o valor de origem para todos os arquivos de destino sem traduzi-lo. Use para valores que precisam permanecer idênticos, byte a byte, em todos os idiomas:

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

de.json e fr.json recebem meta.version com a string exata da origem. Se a origem mudar, o próximo lingo push propaga o novo valor para todos os idiomas, ainda sem tradução.

Preservar — proteger um destino escrito manualmente#

preservedKeys instrui a engine a nunca sobrescrever um valor de destino que já exista. Use quando uma chave precisar de tradução humana — texto legal, texto de compliance, qualquer conteúdo que você já revisou e não quer que o modelo altere:

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

A engine preenche a chave com base na origem na primeira tradução e, depois disso, deixa suas edições intactas em todas as execuções seguintes. Compare com overrides abaixo.

Ignorar — remover a chave da saída#

ignoredKeys remove completamente a chave dos arquivos de destino — ela não é traduzida, copiada nem gravada. Use para strings de debug, flags internas e dados de teste que nunca devem chegar a uma build traduzida:

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

Overrides vs. preserve#

Há duas formas de um valor de destino existente sobreviver a uma execução:

• Preservar (preservedKeys) — declarativo. A chave fica protegida pela configuração, em todos os idiomas, para sempre.
• Edições locais — lingo push compara o hash de cada destino com o lockfile. Se você editou manualmente um arquivo de destino, o push reporta isso como skipped (local edits) e o deixa intacto. Passe --force (com um escopo) para sobrescrever. Veja lingo push.

Use preservedKeys quando a proteção for permanente e válida para todos os idiomas; conte com a detecção de edições locais para ajustes manuais pontuais.

Migrando da CLI legada#

A CLI legada também tinha renomeação de chaves (carregar uma tradução adiante quando o identificador de uma chave mudava). Isso não faz parte da CLI atual — o estado da tradução é rastreado por hash de arquivo, então renomear uma chave faz com que ela seja traduzida novamente no próximo push. Fixar, preservar e ignorar continuam valendo, com uma mudança: os caminhos usam notação de ponto/colchetes (meta.version) em vez da antiga notação com barras (meta/version).