Controlos de chaves

Na maioria dos casos, vai querer traduzir todas as strings de um ficheiro. Para as exceções — nomes de marcas, feature flags, texto jurídico, conteúdo interno irrelevante — o CLI dá-lhe três controlos por ficheiro, definidos numa entrada files[] em .lingo/config.json.

Controlo	Campo de configuração	O que o motor faz
Fixar	`lockedKeys`	Copia o valor de origem para todos os destinos, sem o traduzir.
Preservar	`preservedKeys`	Mantém o que já estiver no destino, sem nunca o substituir.
Ignorar	`ignoredKeys`	Omite totalmente a chave do ficheiro de destino.

Os três aceitam caminhos de chave em notação de ponto/parênteses retos que refletem a estrutura do ficheiro:

json

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

Fixar — manter o valor exatamente igual em todo o lado#

lockedKeys copia o valor de origem para todos os ficheiros de destino sem o traduzir. Use-o para valores que têm de se manter exatamente iguais, byte por byte, em todos os idiomas:

json

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

de.json e fr.json recebem meta.version com a string de origem exata. Altere a origem e o lingo push seguinte propaga o novo valor a todos os idiomas, continuando sem tradução.

Preservar — proteger um destino escrito manualmente#

preservedKeys diz ao motor para nunca substituir um valor de destino que já exista. Use-o quando uma chave precisar de tradução humana — texto jurídico, texto de conformidade, qualquer conteúdo que já tenha revisto e em que não queira que o modelo mexa:

json

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

O motor inicializa a chave a partir da origem na primeira tradução e, a partir daí, deixa as suas edições intactas em todas as execuções seguintes. Compare com overrides abaixo.

Ignorar — excluir a chave do resultado#

ignoredKeys remove totalmente a chave dos ficheiros de destino — não é traduzida, copiada nem escrita. Use-o para strings de depuração, sinalizadores internos e dados de teste que nunca devem chegar a uma build traduzida:

json

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

JSON e JSONC

Os controlos de chaves funcionam em formatos estruturados de chave/valor — json e jsonc. Para formatos da família markdown, delimite a tradução com translateFrontmatterFields e translateComponentProps (consulte Formats).

Overrides vs. preservar#

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 editou manualmente um ficheiro de destino, o push assinala-o como skipped (local edits) e deixa-o intacto. Passe --force (com um âmbito) para o substituir. Consulte lingo push.

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

Migrar do CLI antigo#

O CLI antigo também incluía renomeação de chaves (transportar uma tradução quando o identificador de uma chave mudava). Isso não faz parte do CLI atual — o estado da tradução é acompanhado por hash de ficheiro, por isso, ao renomear uma chave, ela volta a ser traduzida no push seguinte. Fixar, preservar e ignorar transitam todos, com uma alteração: os caminhos usam notação de ponto/parênteses retos (meta.version) em vez da antiga notação com barras (meta/version).