Âmbitos de tradução
Selecione ficheiros e chaves estáveis sem confundir atualizações incrementais, cobertura dos idiomas de destino e atualizações deliberadas.
Uma alteração de localização pode afetar um ficheiro, um idioma ou um conjunto de mensagens. A CLI seleciona cada uma destas dimensões de forma diferente: a configuração do projeto seleciona os ficheiros e os idiomas de destino; os padrões posicionais restringem os ficheiros e alteram o planeamento; --key seleciona as mensagens por chave estável.
O âmbito dos ficheiros altera o plano #
lingo push 'locales/en.json' --waitO padrão limita a seleção aos ficheiros de origem configurados que lhe correspondem. Num formato com ficheiros separados, este comando cria os destinos em falta e deixa os existentes inalterados, mesmo que a origem tenha mudado. Se deixar idiomas configurados de fora da tarefa, preserva a referência de origem existente para que um push normal posterior possa processar essas alterações. Se ainda não existir uma referência, pode inicializá-la.
Para alterações de rotina na origem, utilize apenas lingo push --wait. Para substituir deliberadamente ficheiros inteiros em formatos com ficheiros separados, indique um âmbito posicional com --force, tendo em conta que forçar a operação descarta o contexto de destino existente. Os catálogos XCStrings continuam a poder reutilizar traduções incorporadas; consulte atualizações de catálogos. Os destinos são sempre definidos por targetLocales; o comando push não tem a opção --locale nem a opção --target-locale.
Atualização por chave estável #
lingo push 'locales/en.json' --key 'checkout.title' --key 'checkout.submit' --waitRepita --key para fazer várias seleções. Uma chave é um caminho com pontos ou parênteses retos, como checkout.title ou items[0].title. Selecionar um objeto inclui todas as cadeias de texto que este contém. Assim, auth.login inclui auth.login.title sem selecionar auth.login_url. * representa um segmento completo e [] representa cada elemento de uma matriz; os padrões com caracteres universais parciais, como auth.log*, são rejeitados. Um padrão que comece por $. ou $[ é interpretado diretamente como uma consulta JSONPath. Coloque os padrões com caracteres universais entre aspas.
Os padrões escritos para a versão anterior da CLI com / também funcionam. Um padrão que contenha / é dividido apenas por /, e cada nome é tratado como um todo: auth/login seleciona as mesmas chaves que auth.login, e common/error.message seleciona a chave error.message em common. Os nomes com codificação percentual, como legal/Terms%20of%20use, são descodificados; um padrão sem / é um caminho separado por pontos e não é descodificado, pelo que deve escrever um nome codificado isolado em JSONPath, por exemplo, $['Terms of use']. Como todos os padrões com / são interpretados desta forma, uma chave cujo nome contenha / requer JSONPath, como $.routes['/about'].title. Nesta forma, * representa um nome completo, e um * no final, como em auth/*, seleciona os valores diretamente sob auth, mas não os objetos ou matrizes aí aninhados, tal como fazia a versão anterior da CLI. Um /** no final abrange tudo o que se encontra sob o nome que o precede: auth/** equivale a auth, e auth/*/** abrange também os objetos e matrizes sob auth que auth/* deixa de fora. Um número como items/0 seleciona o elemento da matriz ou a chave de objeto "0", consoante o que existir no documento. São rejeitados os padrões glob dentro de um nome, ** antes do final, parênteses retos e nomes vazios como a//b.
| Formatos | Âmbito por chave |
|---|---|
| JSON/JSONC, PHP, TypeScript, ficheiros de propriedades Java | Volta a gerar as cadeias de texto selecionadas, mesmo quando os valores de origem não foram alterados. |
| YAML/YAML com chave de raiz | Seleciona chaves estáveis, mas as cadeias de texto selecionadas que não tenham sido alteradas podem reutilizar traduções existentes. |
| gettext, ARB, Apple strings, XCStrings, CSV, Android, XLIFF | Não suportado; --key interrompe o push com um erro. |
| Markdown, MDX, Markdoc, HTML, OpenAPI YAML, SubRip, texto simples, Apple stringsdict | Sem chaves estáveis; estes formatos são ignorados com uma mensagem. |
A atualização por chave requer destinos existentes. Os idiomas em falta e os formatos sem chaves estáveis são ignorados, com as respetivas mensagens, em vez de serem inicializados. O preenchimento cria os ficheiros normais em falta, mas não preenche lacunas nos ficheiros existentes. Adicionar --force não altera o planeamento por chave nem impede a reutilização em YAML.
A atualização por chave deixa inalterada a referência de toda a origem, quer a recolha seja feita por push --wait ou por um pull separado. Por isso, as alterações normais pendentes na origem continuam a ser processadas no próximo push normal.
Atualizar após alterar as orientações #
Editar o glossário ou as regras de um motor de localização não altera os bytes dos ficheiros de origem. Por isso, um push normal pode não ter qualquer efeito. Para JSON, JSONC, TypeScript e PHP, selecione as chaves estáveis afetadas. Para YAML, edite diretamente o destino para fazer uma correção precisa ou guarde os destinos aceites e utilize --force para ficheiros inteiros, com âmbito limitado e sem --key, para os voltar a gerar. Inspecione todo o ficheiro resultante, pois essa substituição também pode alterar mensagens adjacentes. Os controlos de chaves determinam que valores de origem ou de destino são preservados na reconstrução; não selecionam o trabalho a realizar.
Para uma alteração de grande dimensão, escolha um âmbito suficientemente pequeno para permitir a inspeção e a recuperação e, em seguida, faça uma estimativa antes de submeter. A estimativa carrega os ficheiros necessários e planeia o trabalho sem criar uma tarefa de tradução.
Voltar a traduzir um único idioma #
Num projeto com um ficheiro separado para cada idioma, remova os destinos desse idioma e preencha os ficheiros em falta. Primeiro, conclua as atualizações pendentes da origem e guarde as traduções aceites. A limpeza filtrada preserva as referências de origem e as entradas do Lockfile dos outros idiomas.
Para uma origem configurada em locales/en.json, pré-visualize a eliminação do destino em francês:
lingo purge --locale fr --file locales/en.jsonInspecione os caminhos apresentados. Se corresponderem aos destinos pretendidos, confirme a eliminação e crie as traduções em falta:
lingo purge --locale fr --file locales/en.json --yes
lingo push --backfill-missing --waitNuma configuração que utilize padrões glob, como locales/en/*.json, indique caminhos de origem concretos, repetindo a opção --file em ambos os comandos de limpeza. O comando de limpeza não expande os padrões glob por si só. Inclua todas as origens cujo destino em francês pretende voltar a gerar e, antes do preenchimento, verifique se não faltam outros ficheiros de destino: o preenchimento cria todos os destinos configurados que estejam em falta.
Quando a operação terminar, inspecione o resultado em francês e registe-o num commit juntamente com o Lockfile atualizado. Os ficheiros de destino existentes dos outros idiomas permanecem inalterados. Consulte Limpeza para conhecer as regras de seleção. Este procedimento não se aplica a catálogos XCStrings, nos quais a origem e todos os idiomas de destino partilham um único ficheiro.