Controles de chaves
Escolha se um valor vem do conteúdo de origem, de um destino existente, da tradução ou dos metadados do idioma.
Alguns valores do catálogo devem ser idênticos em todos os idiomas. Outros ficam a cargo de quem mantém o conteúdo de destino. Os controles de chaves deixam essas escolhas explícitas quando um processador de arquivos compatível reconstrói a saída.
Essas opções são definidas por entrada de arquivo em .lingo/config.json. Elas não selecionam arquivos nem solicitam a atualização de chaves; isso fica a cargo dos escopos de tradução.
| Controle | Comportamento da saída |
|---|---|
lockedKeys | Copiar o valor de origem sem traduzi-lo. |
preservedKeys | Manter o valor de destino existente, quando disponível. |
ignoredKeys | Remover o conteúdo selecionado da saída de um formato compatível. |
injectLocale | Gravar o idioma de destino no local selecionado. |
Defina um responsável para cada valor #
{
"pattern": "locales/en.json",
"lockedKeys": ["product.id"],
"preservedKeys": ["legal.notice"],
"ignoredKeys": ["internal.note"],
"injectLocale": { "enabled": true, "key": "meta.locale" }
}Neste exemplo, o ID do produto vem da origem, o aviso legal existente no destino é mantido e a nota interna é omitida. A injeção de idioma grava o idioma de destino em meta.locale, criando os objetos que faltam para conter o valor, quando necessário. Para locais em arrays, forneça um array existente e selecione um elemento existente ou a posição imediatamente após o fim do array; caminhos que criam lacunas ou passam por valores incompatíveis resultam em erro.
A preservação não cria uma tradução humana onde ela não existe. O processamento incremental normal já usa o conteúdo de destino existente para manter as edições feitas em chaves que não mudaram; preservedKeys oferece uma proteção explícita além desse comportamento. Uma alteração na origem ou a renomeação de uma chave JSON ainda pode exigir novo trabalho.
Caminhos e controles sobrepostos #
Os controles de JSON/JSONC usam nomes separados por pontos e índices entre colchetes, como checkout.submit ou items[0].title. Um caminho protegido pode abranger seus descendentes. Use uma propriedade JSONPath entre aspas, como $['checkout.submit'], quando o nome literal de uma chave contiver um ponto. lingo push também lê listas escritas para a CLI anterior com /: cada nome entre / é interpretado por inteiro, de modo que checkout/submit equivale a checkout.submit e common/error.message indica a chave error.message dentro de common. Nomes com codificação percentual, como legal/Terms%20of%20use, são decodificados; um padrão sem / é um caminho separado por pontos e não é decodificado. Por isso, escreva um nome codificado isolado como JSONPath, por exemplo, $['Terms of use']. Como todo padrão com / é lido dessa forma, uma chave cujo nome contém / precisa ser escrita como JSONPath, como $.routes['/about'].title. Um * no final, como em internal/*, abrange os valores diretamente em internal, mas não os objetos ou arrays aninhados nesse local, assim como na CLI anterior. A CLI anterior também reconhecia chaves cujos nomes continuavam com - ou ., de modo que legal/terms abrangia legal/terms-short. Essa correspondência por prefixo foi removida; liste essas chaves separadamente. O GitHub App não aceita a forma com barras: quando o GitHub App ler a mesma configuração, escreva essas listas com pontos ou como JSONPath. Escopos descreve essa forma.
No mesmo local, uma regra de exclusão remove o valor, inclusive um valor de idioma injetado. A injeção de idioma tem precedência sobre o bloqueio e a preservação. O bloqueio tem precedência sobre a preservação, de modo que uma chave presente nas duas listas usa o valor de origem. Ignorar um ancestral também remove seus descendentes. Sempre que possível, defina um único responsável para cada valor e confira a saída quando houver sobreposição de regras em um objeto ou array.
Forçar o processamento do arquivo inteiro limpa o artefato de destino atual enviado ao servidor. Sem esse contexto de destino, uma regra de preservação não consegue manter o texto escrito anteriormente por uma pessoa. Guarde uma cópia recuperável antes da substituição forçada.
Limitações dos processadores #
JSON e JSONC oferecem suporte aos quatro controles. TypeScript, PHP, YAML e YAML com idioma na raiz permitem bloquear, preservar e ignorar; stringsdict permite bloquear e preservar. Arquivos de propriedades Java oferecem suporte a bloqueio, preservação, exclusão do processamento e escopo de chaves, comparando cada padrão com a chave inteira, como fazia a versão anterior da CLI. CSV não oferece suporte a nenhuma das três regras de chave: a CLI e o GitHub App rejeitam uma entrada CSV que defina lockedKeys, preservedKeys ou ignoredKeys. Consulte a Referência do formato escolhido para entender como a saída é gerada.
A forma curta de caminho aceita * como segmento inteiro, índices numéricos e colchetes vazios. Ela rejeita curingas parciais. Com lingo push, as três listas de regras de chaves também aceitam a forma com barras; o GitHub App e o local de injeção não aceitam essa forma. Use propriedades JSONPath entre aspas para nomes literais que contenham pontuação; consultas explícitas $ são repassadas sem alterações. A injeção exige um único local e, quando ativada, usa language como chave padrão.