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.
lingo check --jsonQuais verificações são realizadas #
| Verificação | Quando é executada |
|---|---|
| Verificação de arquivos | .lingo/config.json tem files, ou o projeto não é React. |
| Verificações do React | O 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.
| Caso | Problema | Correção |
|---|---|---|
| Um arquivo de origem corresponde à sua entrada no Lockfile e seus destinos existem | nenhum | |
Nenhum padrão de files corresponde a um arquivo | no-source-files | Corrija os padrões de files |
| Um arquivo de origem foi alterado desde a última tradução | source-changed | lingo push --wait, ou lingo pull se um push ainda estiver em execução |
| Um arquivo de origem não tem entrada no Lockfile | source-not-pushed | lingo push --wait |
| Falta um arquivo de destino e sua origem está atualizada | missing-target | lingo push --backfill-missing --wait |
| Falta um arquivo de destino e sua origem foi alterada ou nunca foi enviada | missing-target | lingo push --wait |
| Um arquivo de destino foi editado manualmente | nenhum | |
| Não há Lockfile e todos os arquivos de destino existem | nenhum, com uma observação em stderr | |
| Não há Lockfile e falta um arquivo de destino | missing-target, com uma observação em stderr | lingo 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 #
| Tipo | Possível correção a investigar |
|---|---|
missing-context | Adicione contexto útil à mensagem extraída. |
stale-jsonc | Gere novamente o catálogo de origem e inspecione-o. |
stale-types | Gere novamente as declarações e inclua-as na verificação de tipos da aplicação. |
missing-translation | Inspecione uma chave ativa que não tenha um valor de destino ativo preenchido. |
orphaned | Antes 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:
- uses: actions/checkout@v4
- run: npx @lingo.dev/cli@latest checkUse 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
.jsoncdo 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 pushe o checkout da CI precisam usar as mesmas terminações de linha. Adicione* text=auto eol=lfa.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.