Escopos de tradução
Selecione arquivos e chaves estáveis sem misturar atualizações incrementais, cobertura dos idiomas de destino e atualizações intencionais.
Uma alteração de localização pode afetar um arquivo, um idioma ou um conjunto de mensagens. A CLI seleciona cada uma dessas dimensões de forma diferente: a configuração do projeto seleciona arquivos e idiomas de destino; os padrões posicionais restringem os arquivos e alteram o planejamento; --key seleciona mensagens por chave estável.
O escopo de arquivos altera o plano #
lingo push 'locales/en.json' --waitO padrão restringe o conjunto de arquivos de origem configurados. Em formatos com arquivos separados, esse comando cria os destinos ausentes e mantém os existentes inalterados, mesmo quando a origem mudou. Se algum idioma configurado ficar fora da tarefa, o comando preserva a referência de origem existente para que um push simples posterior ainda possa processar essas edições. Se ainda não houver uma referência, ele poderá inicializá-la.
Para edições de rotina na origem, use apenas lingo push --wait. Para substituir intencionalmente arquivos inteiros em formatos com arquivos separados, informe um escopo posicional com --force, sabendo que a opção de forçar descarta o contexto de destino existente. Os catálogos XCStrings ainda podem reutilizar traduções incorporadas; consulte atualizações de catálogos. Os destinos sempre vêm de targetLocales; o push não tem as opções --locale ou --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 em notação de pontos ou colchetes, como checkout.title ou items[0].title. Selecionar um objeto inclui todas as strings contidas nele. Assim, auth.login inclui auth.login.title sem selecionar auth.login_url. * representa um segmento inteiro e [], cada item de um array; curingas parciais, como auth.log*, são rejeitados. Um padrão que começa com $. ou $[ é repassado como uma consulta JSONPath. Coloque os padrões com curingas entre aspas.
Os padrões escritos para a versão anterior da CLI com / também funcionam. Um padrão que contém / é dividido apenas em /, 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. Nomes com codificação percentual, como legal/Terms%20of%20use, são decodificados; um padrão sem / é um caminho em notação de pontos e não é decodificado. Por isso, para um único nome codificado, use JSONPath, como $['Terms of use']. Como todo padrão com / é interpretado dessa forma, uma chave cujo nome contém / precisa de JSONPath, como $.routes['/about'].title. Nessa forma, * representa um nome inteiro, e um * no final, como em auth/*, seleciona os valores diretamente em auth, mas não os objetos ou arrays aninhados ali, assim como fazia a versão anterior da CLI. Um /** no final abrange tudo sob o nome que o precede: auth/** equivale a auth, e auth/*/** também abrange os objetos e arrays em auth que auth/* deixa de fora. Um número como items/0 seleciona o item do array ou a chave de objeto "0", conforme o que houver no documento. São rejeitados curingas dentro de um nome, ** antes do final, colchetes e nomes vazios, como a//b.
| Formatos | Escopo de chaves |
|---|---|
| JSON/JSONC, PHP, TypeScript, arquivos de propriedades Java | Regenera as strings selecionadas, mesmo quando os valores de origem não mudaram. |
| YAML/YAML com chave raiz | Seleciona chaves estáveis, mas as strings selecionadas que não mudaram podem reutilizar traduções existentes. |
| gettext, ARB, Apple strings, XCStrings, CSV, Android, XLIFF | Não há suporte; --key interrompe o push com um erro. |
| Markdown, MDX, Markdoc, HTML, OpenAPI YAML, SubRip, texto simples, Apple stringsdict | Não têm chaves estáveis; são ignorados com uma mensagem. |
A atualização por chave exige destinos existentes. Idiomas ausentes e formatos sem chaves estáveis são ignorados com mensagens, em vez de serem inicializados. O preenchimento cria arquivos comuns ausentes, mas não preenche lacunas nos arquivos existentes. Adicionar --force não altera o planejamento por escopo de chaves nem impede a reutilização em YAML.
A atualização por chave mantém inalterada a referência da origem completa, seja ela coletada por push --wait ou por um pull separado. Assim, as edições comuns pendentes na origem ainda serão processadas no próximo push simples.
Atualizar após alterar as orientações #
Editar o glossário ou as regras de um engine de localização não altera os bytes do arquivo de origem. Por isso, um push simples pode não executar nenhuma ação. Para JSON, JSONC, TypeScript e PHP, selecione as chaves estáveis afetadas. Para YAML, edite o destino diretamente para fazer uma correção pontual ou salve os destinos aceitos e use --force com escopo de arquivo inteiro, sem --key, para regenerá-los. Revise todo o arquivo resultante, pois essa substituição também pode alterar mensagens vizinhas. Os controles de chaves determinam quais valores de origem ou destino são preservados na reconstrução; eles não selecionam o trabalho a ser feito.
Para uma alteração grande, escolha um escopo pequeno o suficiente para revisar e recuperar e, em seguida, faça uma estimativa antes do envio. A estimativa envia os arquivos necessários e planeja o trabalho sem criar uma tarefa de tradução.
Retraduzir um único idioma #
Em um projeto com um arquivo separado para cada idioma, remova os destinos desse idioma e preencha os arquivos ausentes. Antes disso, conclua as atualizações pendentes na origem e salve as traduções aceitas. A limpeza com filtro preserva as referências de origem e as entradas do Lockfile para os outros idiomas.
Para uma origem configurada em locales/en.json, confira a prévia da exclusão do destino em francês:
lingo purge --locale fr --file locales/en.jsonConfira os caminhos informados. Se forem os destinos que você quer remover, confirme a exclusão e crie as traduções ausentes:
lingo purge --locale fr --file locales/en.json --yes
lingo push --backfill-missing --waitPara uma configuração que usa padrões glob, como locales/en/*.json, informe caminhos de origem concretos repetindo a opção --file nos dois comandos de limpeza. A limpeza não expande os padrões glob por conta própria. Inclua todas as origens cujos destinos em francês você quer regenerar e verifique se não há outros arquivos de destino ausentes antes do preenchimento: ele cria todos os destinos configurados que estiverem ausentes.
Ao concluir, revise o resultado em francês e faça o commit dele junto com o Lockfile atualizado. Os arquivos de destino existentes para outros idiomas permanecem inalterados. Consulte Limpeza para ver as regras de seleção. Este procedimento não se aplica aos catálogos XCStrings, nos quais a origem e todos os idiomas de destino compartilham um único arquivo.