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.
lingo check --jsonQuais são as verificações executadas #
| Verificação | Quando é executada |
|---|---|
| Verificação de ficheiros | .lingo/config.json tem files ou o projeto não é React. |
| Verificações 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 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ção | Problema | Correção |
|---|---|---|
| Uma origem corresponde à respetiva entrada no Lockfile e os seus destinos existem | nenhum | |
Nenhum padrão files corresponde a um ficheiro | no-source-files | Corrija os padrões files |
| Uma origem foi alterada desde a última tradução | source-changed | lingo push --wait ou lingo pull se ainda estiver um push em curso |
| Uma origem não tem entrada no Lockfile | source-not-pushed | lingo push --wait |
| Falta um ficheiro de destino e a respetiva origem está atualizada | missing-target | lingo push --backfill-missing --wait |
| Falta um ficheiro de destino e a respetiva origem foi alterada ou nunca foi enviada | missing-target | lingo push --wait |
| Um ficheiro de destino foi editado manualmente | nenhum | |
| Não existe Lockfile e todos os ficheiros de destino existem | nenhum, com uma nota em stderr | |
| Não existe Lockfile e falta um ficheiro de destino | missing-target, com uma nota em stderr | lingo 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 #
| Tipo | Correção a investigar |
|---|---|
missing-context | Adicione contexto útil à mensagem extraída. |
stale-jsonc | Volte a gerar o catálogo de origem e inspecione-o. |
stale-types | Volte a gerar 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 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:
- uses: actions/checkout@v4
- run: npx @lingo.dev/cli@latest checkUtilizar 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 pushe o checkout da CI têm de utilizar os mesmos finais de linha. Adicione* text=auto eol=lfa.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.