Lingo check

Faça a CI falhar quando as traduções estiverem desatualizadas e verifique os catálogos React.

lingo check falha quando as traduções estão desatualizadas. Ele compara cada arquivo de origem com .lingo/lock.json, exige que todos os arquivos de destino existam e, em projetos @lingo.dev/react, também verifica catálogos extraídos, declarações, contexto e traduções.

sh
lingo check --json

Quais verificações são realizadas #

VerificaçãoQuando é executada
Verificação de arquivos.lingo/config.json tem files, ou o projeto não é React.
Verificações do ReactO package.json na raiz, ou o mais próximo de --src, lista @lingo.dev/react, @lingo.dev/react-next ou @lingo.dev/react-tanstack, ou existe um arquivo de declarações gerado (lingo.d.ts por padrão).

Um projeto React com files executa as duas verificações. Se nenhum padrão de files corresponder a um arquivo, a verificação falha com no-source-files, assim como lingo push. A exceção são os projetos React, nos quais apenas as verificações do React são executadas, com um aviso em stderr. Um projeto sem files nem React falha com o mesmo erro de configuração de lingo push.

lingo check não precisa de chave de API e não grava nada. Fora a telemetria da CLI, que pode ser desativada com DO_NOT_TRACK=1, ele não faz chamadas de rede. A execução termina com código 1 ao relatar qualquer problema ou encontrar um erro de configuração (por exemplo, uma colisão de destinos ou um Lockfile corrompido), e com código 0 nos demais casos.

Verificação de arquivos #

As origens são os arquivos que lingo push enviaria. Os destinos são os caminhos em que o comando push gravaria os arquivos de cada idioma de destino configurado.

CasoProblemaCorreção
Um arquivo de origem corresponde à sua entrada no Lockfile e seus destinos existemnenhum
Nenhum padrão de files corresponde a um arquivono-source-filesCorrija os padrões de files
Um arquivo de origem foi alterado desde a última traduçãosource-changedlingo push --wait, ou lingo pull se um push ainda estiver em execução
Um arquivo de origem não tem entrada no Lockfilesource-not-pushedlingo push --wait
Falta um arquivo de destino e sua origem está atualizadamissing-targetlingo push --backfill-missing --wait
Falta um arquivo de destino e sua origem foi alterada ou nunca foi enviadamissing-targetlingo push --wait
Um arquivo de destino foi editado manualmentenenhum
Não há Lockfile e todos os arquivos de destino existemnenhum, com uma observação em stderr
Não há Lockfile e falta um arquivo de destinomissing-target, com uma observação em stderrlingo push --backfill-missing --wait, depois faça commit dos arquivos de destino e de .lingo/lock.json

As entradas do Lockfile referentes a caminhos que não estão mais configurados como origens são ignoradas. Os avisos de destino inferido e de YAML ignorado que lingo push exibe também aparecem aqui, em stderr.

Entenda um problema #

TipoPossível correção a investigar
missing-contextAdicione contexto útil à mensagem extraída.
stale-jsoncGere novamente o catálogo de origem e inspecione-o.
stale-typesGere novamente as declarações e inclua-as na verificação de tipos da aplicação.
missing-translationInspecione uma chave ativa que não tenha um valor de destino ativo preenchido.
orphanedAntes de fazer a limpeza, determine se a mensagem foi removida ou se a extração deixou de detectá-la.

Para consultar os problemas da verificação de arquivos e suas correções, veja Verificação de arquivos.

Saída JSON #

A saída JSON contém issues e stats. A saída em formato legível por humanos lista os mesmos problemas para uso local.

Cada problema tem type e message. Problemas do React podem ter src; problemas de arquivos têm file, e um problema do tipo missing-target também tem locale.

As estatísticas contêm messages, locales, missingContext, missingTranslations, orphaned, staleJsonc e staleTypes, cujos valores são zero ou falso quando as verificações do React não foram executadas. A contagem de idiomas inclui os destinos encontrados e a origem. Quando a verificação de arquivos é executada, stats.files contém lockfile, sources, locales, changedSources e missingTargets. Esses dados descrevem a consistência, não uma medição da qualidade linguística.

Execute na CI #

Execute em cada pull request ou merge request, inclusive nos que vêm de forks:

yaml
- uses: actions/checkout@v4
- run: npx @lingo.dev/cli@latest check

Use as mesmas entradas da extração #

--src, --out, --types e --source-locale se aplicam apenas às verificações do React. O valor padrão de --src é src, e o de --source-locale é en. --out tem precedência sobre o caminho de catálogo configurado, seguido de locales; --types tem precedência sobre o caminho de declarações configurado, seguido de lingo.d.ts. Os caminhos são resolvidos a partir da raiz do projeto. O valor padrão do idioma de origem é independente da configuração de localização. O valor padrão de --json é falso, e essa opção se aplica às duas verificações.

Execute a extração com essas mesmas entradas para atualizar o que estiver desatualizado. Inspecione os avisos e as diferenças e, em seguida, execute novamente a verificação e a compilação da aplicação. Remova apenas as entradas comprovadamente obsoletas e depois gere novamente as declarações.

Limitações #

  • A verificação de arquivos atua no nível dos arquivos. Uma chave ausente em um destino existente não é relatada, exceto em catálogos .jsonc do React.
  • Os idiomas em um único catálogo compartilhado, como um arquivo .xcstrings, não são verificados, e uma edição manual nesse catálogo conta como alteração na origem.
  • Um repositório que migrou da CLI para o GitHub App deve excluir .lingo/lock.json.
  • Erros de configuração, como duas origens que apontam para o mesmo destino ou um Lockfile corrompido, encerram a execução com código 1, uma mensagem em stderr e nenhuma saída JSON.
  • Os hashes de origem consideram cada byte. Por isso, o checkout que executou lingo push e o checkout da CI precisam usar as mesmas terminações de linha. Adicione * text=auto eol=lf a .gitattributes.

Nos catálogos React, os destinos são os arquivos .jsonc no diretório do catálogo. Quando os padrões de files correspondem ao catálogo de origem (por exemplo, locales/en.jsonc), os arquivos de todos os idiomas de destino configurados também são obrigatórios.

Apenas os avisos de extração sobre contexto ausente se tornam problemas de contexto. Os avisos de expressões dinâmicas e as informações sobre colisões não formam um conjunto completo de critérios de falha aqui; a própria extração garante a falha em caso de colisão. Um texto provisório não vazio no idioma de origem também pode passar na verificação de presença sem ser uma tradução.

Use extract --check quando só for necessário verificar se os bytes gerados estão atualizados. Mantenha a validação do formato nativo e a revisão de conteúdo em conjunto com este verificador; passar na verificação não garante nada sobre recursos do Android, renderização de Markdown ou o significado das traduções além do que ele efetivamente verifica.