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. Compara cada ficheiro de origem com .lingo/lock.json, exige que todos os ficheiros de destino existam e, em projetos @lingo.dev/react, verifica também os catálogos extraídos, as declarações, o contexto e as traduções.

sh
lingo check --json

Quais são as verificações executadas #

VerificaçãoQuando é executada
Verificação de ficheiros.lingo/config.json tem files ou o projeto não é React.
Verificações 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 o ficheiro de declarações gerado (lingo.d.ts por predefinição).

Num projeto React com files, são executadas ambas as verificações. Se nenhum padrão files corresponder a um ficheiro, a verificação falha com no-source-files, tal como acontece com lingo push. A exceção são os projetos React: nesse caso, só são executadas as verificações React, com uma indicação em stderr. Um projeto sem files nem React falha com o mesmo erro de configuração que lingo push.

lingo check não requer uma chave de API nem escreve nada. À exceção da telemetria da CLI, que DO_NOT_TRACK=1 desativa, não faz chamadas de rede. Termina com o código 1 se detetar algum problema ou encontrar um erro de configuração (por exemplo, uma colisão de destinos ou um Lockfile corrompido) e com o código 0 nos restantes casos.

Verificação de ficheiros #

As origens são os ficheiros que lingo push enviaria. Os destinos são os caminhos onde o comando push escreveria os ficheiros de cada idioma de destino configurado.

SituaçãoProblemaCorreção
Uma origem corresponde à respetiva entrada no Lockfile e os seus destinos existemnenhum
Nenhum padrão files corresponde a um ficheirono-source-filesCorrija os padrões files
Uma origem foi alterada desde a última traduçãosource-changedlingo push --wait ou lingo pull se ainda estiver um push em curso
Uma origem não tem entrada no Lockfilesource-not-pushedlingo push --wait
Falta um ficheiro de destino e a respetiva origem está atualizadamissing-targetlingo push --backfill-missing --wait
Falta um ficheiro de destino e a respetiva origem foi alterada ou nunca foi enviadamissing-targetlingo push --wait
Um ficheiro de destino foi editado manualmentenenhum
Não existe Lockfile e todos os ficheiros de destino existemnenhum, com uma nota em stderr
Não existe Lockfile e falta um ficheiro de destinomissing-target, com uma nota em stderrlingo push --backfill-missing --wait e, em seguida, registe os ficheiros de destino e .lingo/lock.json num commit

As entradas do Lockfile relativas a caminhos que já não estão configurados como origens são ignoradas. Os avisos sobre destinos inferidos e ficheiros YAML ignorados apresentados por lingo push também aparecem aqui, em stderr.

Interpretar um problema #

TipoCorreção a investigar
missing-contextAdicione contexto útil à mensagem extraída.
stale-jsoncVolte a gerar o catálogo de origem e inspecione-o.
stale-typesVolte a gerar 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 efetuar a limpeza, determine se a mensagem foi removida ou se a extração não a detetou.

Para conhecer os problemas da verificação de ficheiros e as respetivas correções, consulte Verificação de ficheiros.

Saída JSON #

A saída JSON contém issues e stats. A saída em formato legível lista os mesmos problemas para utilização local.

Cada problema tem type e message. Os problemas React podem ter src; os problemas de ficheiros têm file, e um problema 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 false quando as verificações React não foram executadas. A contagem de idiomas inclui os destinos detetados e a origem. Quando a verificação de ficheiros é executada, stats.files contém lockfile, sources, locales, changedSources e missingTargets. Estes valores descrevem a consistência; não medem a qualidade linguística.

Executar na CI #

Execute em cada pedido de integração ou de fusão, incluindo os provenientes de bifurcações:

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

Utilizar os mesmos parâmetros da extração #

--src, --out, --types e --source-locale aplicam-se apenas às verificações React. --src tem como valor predefinido src e --source-locale tem como valor predefinido en. --out tem prioridade sobre o caminho do catálogo configurado, seguindo-se locales; --types tem prioridade sobre o caminho das declarações configurado, seguindo-se lingo.d.ts. Os caminhos são resolvidos a partir da raiz do projeto. O valor predefinido do idioma de origem é independente da configuração de localização. --json tem como valor predefinido false e aplica-se a ambas as verificações.

Execute a extração com os mesmos parâmetros para atualizar o que estiver desatualizado. Inspecione os avisos e as diferenças e, em seguida, volte a executar a verificação e a compilação da aplicação. Limpe apenas as entradas confirmadas como obsoletas e volte a gerar as declarações depois da limpeza.

Limitações #

  • A verificação de ficheiros atua ao nível dos ficheiros. Uma chave em falta num destino existente não é assinalada, exceto nos catálogos React .jsonc.
  • Os idiomas num único catálogo partilhado, como um ficheiro .xcstrings, não são verificados, e uma edição manual nesse catálogo conta como uma alteração da origem.
  • Um repositório que tenha migrado da CLI para a GitHub App deve eliminar .lingo/lock.json.
  • Os erros de configuração, como duas origens cujos caminhos apontam para o mesmo destino ou um Lockfile corrompido, fazem a execução terminar com o código 1, com uma mensagem em stderr e sem JSON.
  • Os hashes de origem são exatos ao nível dos bytes, pelo que o checkout que executou lingo push e o checkout da CI têm de utilizar os mesmos finais de linha. Adicione * text=auto eol=lf a .gitattributes.

Nos catálogos React, os destinos são os ficheiros .jsonc no diretório do catálogo. Quando os padrões files correspondem ao catálogo de origem (por exemplo, locales/en.jsonc), também é necessário que exista o ficheiro de cada idioma de destino configurado.

Apenas os avisos de extração por falta de contexto são tratados como problemas de contexto. Os avisos sobre expressões dinâmicas e as informações sobre colisões não constituem aqui um critério exaustivo para determinar a falha; a própria extração falha em caso de colisão. Um marcador de posição não vazio no idioma de origem também pode passar na verificação de presença sem ser uma tradução.

Utilize extract --check quando apenas for necessário garantir que os bytes gerados estão atualizados. Mantenha a validação nativa do formato e a revisão do conteúdo a par deste verificador; passar na verificação nada diz sobre os recursos Android, a apresentação de Markdown ou o significado da tradução para além do que é efetivamente verificado.