Controlos de chaves

Escolha se um valor deve vir do conteúdo de origem, de um destino existente, da tradução ou dos metadados do idioma.

Alguns valores do catálogo devem ser iguais em todos os idiomas. Outros devem ficar a cargo de quem mantém o conteúdo de destino. Os controlos de chaves tornam estas escolhas explícitas quando um processador de ficheiros compatível reconstrói o resultado.

Estas opções são definidas por entrada de ficheiro em .lingo/config.json. Não selecionam ficheiros nem pedem uma atualização das chaves; essa é a função dos âmbitos de tradução.

ControloComportamento do resultado
lockedKeysCopiar o valor de origem sem o traduzir.
preservedKeysManter o valor de destino existente, quando disponível.
ignoredKeysRemover o conteúdo selecionado do resultado de um formato compatível.
injectLocaleEscrever o idioma de destino na localização selecionada.

Atribua um responsável a cada valor #

json
{
  "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 é mantido a partir do destino e a nota interna é omitida. A injeção de idioma escreve o idioma de destino em meta.locale, criando os objetos em falta quando necessário. Para localizações em matrizes, forneça uma matriz existente e selecione um elemento existente ou a posição imediatamente a seguir ao fim da matriz; os caminhos que criem lacunas ou atravessem valores incompatíveis falham.

A preservação não consegue criar uma tradução humana onde ela não existe. O processamento incremental normal já utiliza o conteúdo de destino existente para manter as edições feitas em chaves inalteradas; preservedKeys acrescenta uma proteção explícita para além desse comportamento. Uma alteração na origem ou a mudança de nome de uma chave JSON pode, ainda assim, exigir novo trabalho.

Caminhos e controlos sobrepostos #

Os controlos JSON/JSONC utilizam nomes separados por pontos e índices entre parênteses retos, como checkout.submit ou items[0].title. Um caminho protegido pode abranger os seus descendentes. Utilize 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 na íntegra, pelo que checkout/submit equivale a checkout.submit e common/error.message designa a chave error.message dentro de common. Os nomes com codificação percentual, como legal/Terms%20of%20use, são descodificados; um padrão sem / é um caminho com pontos e não é descodificado, pelo que deve escrever um nome codificado isolado como JSONPath, por exemplo, $['Terms of use']. Como todos os padrões com / são lidos desta forma, uma chave cujo nome contenha / requer JSONPath, como $.routes['/about'].title. Um * no final, como em internal/*, abrange os valores diretamente dentro de internal, mas não os objetos ou matrizes aí aninhados, tal como na CLI anterior. A CLI anterior também fazia a correspondência com chaves cujos nomes continuavam com - ou ., pelo que legal/terms abrangia legal/terms-short. Essa correspondência por prefixo deixou de existir; liste essas chaves separadamente. A GitHub App não aceita a forma com barras: quando a aplicação lê a mesma configuração, escreva estas listas com pontos ou como JSONPath. Âmbitos descreve esta forma.

Na mesma localização, uma regra de exclusão remove o valor, mesmo que seja um valor de idioma injetado. A injeção de idioma tem prioridade sobre o bloqueio e a preservação. O bloqueio tem prioridade sobre a preservação, pelo que uma chave presente em ambas as listas utiliza o valor de origem. A exclusão de um elemento ascendente também remove os seus descendentes. Sempre que possível, atribua um único responsável a cada valor e verifique o resultado quando as regras se sobrepuserem num objeto ou numa matriz.

A substituição forçada de todo o ficheiro remove o artefacto de destino atual enviado ao servidor. Sem esse contexto de destino, uma regra de preservação não consegue manter a redação humana anterior. Guarde uma cópia recuperável antes de efetuar uma substituição forçada.

Limites dos manipuladores #

JSON e JSONC suportam os quatro controlos. TypeScript, PHP, YAML e YAML com raiz por idioma suportam o bloqueio, a preservação e a opção de ignorar; stringsdict suporta o bloqueio e a preservação. O formato Java properties suporta o bloqueio, a preservação, a opção de ignorar e o âmbito das chaves, comparando cada padrão com a chave completa, tal como fazia a versão anterior da CLI. CSV não suporta nenhuma das três regras de chaves: a CLI e a GitHub App rejeitam qualquer entrada CSV que defina lockedKeys, preservedKeys ou ignoredKeys. Consulte a Referência do formato escolhido para saber como é gerada a saída.

A forma curta dos caminhos suporta * para segmentos completos, índices numéricos e parênteses retos vazios. Não aceita carateres universais parciais. Com lingo push, as três listas de regras de chaves também aceitam a forma com barras; a GitHub App e a localização de injeção não a aceitam. Utilize propriedades JSONPath entre aspas para nomes literais que contenham pontuação; as consultas $ explícitas são transmitidas sem alterações. A injeção requer uma única localização e, quando ativada, utiliza language como chave predefinida.