Lingo check

Faites échouer la CI lorsque les traductions ne sont plus à jour et vérifiez les catalogues React.

lingo check échoue lorsque les traductions ne sont plus à jour. Il compare chaque fichier source à .lingo/lock.json, exige la présence de tous les fichiers cibles et, dans les projets @lingo.dev/react, vérifie également les catalogues extraits, les déclarations, le contexte et les traductions.

sh
lingo check --json

Quelles vérifications sont effectuées #

VérificationConditions d’exécution
Vérification des fichiers.lingo/config.json contient files, ou le projet n’utilise pas React.
Vérifications ReactLe fichier package.json à la racine, ou celui le plus proche de --src, répertorie @lingo.dev/react, @lingo.dev/react-next ou @lingo.dev/react-tanstack, ou le fichier de déclarations généré (lingo.d.ts par défaut) existe.

Un projet React avec files exécute les deux types de vérifications. Si aucun motif files ne correspond à un fichier, la vérification échoue avec no-source-files, comme le fait lingo push. Dans un projet React, en revanche, seules les vérifications React s’exécutent, et stderr le signale. Un projet sans files ni React échoue avec la même erreur de configuration que lingo push.

lingo check ne nécessite aucune clé API et n’écrit rien. Hormis la télémétrie de la CLI, que DO_NOT_TRACK=1 désactive, il n’effectue aucun appel réseau. Il se termine avec le code 1 s’il signale un problème ou rencontre une erreur de configuration (par exemple, une collision de cibles ou un Lockfile corrompu), et avec le code 0 dans les autres cas.

Vérification des fichiers #

Les sources sont les fichiers que lingo push enverrait. Les cibles sont les chemins où push écrirait les fichiers pour chaque langue cible configurée.

CasProblèmeCorrection
Une source correspond à son entrée dans le Lockfile et ses cibles existentaucun
Aucun motif files ne correspond à un fichierno-source-filesCorrigez les motifs files
Une source a changé depuis sa dernière traductionsource-changedlingo push --wait, ou lingo pull si un push est encore en cours
Une source n’a aucune entrée dans le Lockfilesource-not-pushedlingo push --wait
Un fichier cible manque et sa source est à jourmissing-targetlingo push --backfill-missing --wait
Un fichier cible manque et sa source a changé ou n’a jamais été envoyéemissing-targetlingo push --wait
Un fichier cible a été modifié manuellementaucun
Le Lockfile est absent et tous les fichiers cibles existentaucun, avec une note sur stderr
Le Lockfile est absent et un fichier cible manquemissing-target, avec une note sur stderrlingo push --backfill-missing --wait, puis committez les fichiers cibles et .lingo/lock.json

Les entrées du Lockfile correspondant à des chemins qui ne sont plus configurés comme sources sont ignorées. Les avertissements de lingo push concernant les cibles déduites et les fichiers YAML ignorés apparaissent également ici, sur stderr.

Comprendre un problème #

TypePiste de correction à explorer
missing-contextAjoutez un contexte utile au message extrait.
stale-jsoncRégénérez le catalogue source et examinez-le.
stale-typesRégénérez les déclarations et incluez-les dans la vérification des types de l’application.
missing-translationExaminez une clé active qui ne possède aucune valeur cible active non vide.
orphanedAvant de procéder au nettoyage, déterminez si le message a été supprimé ou si l’extraction l’a omis.

Pour les problèmes liés à la vérification des fichiers et leurs corrections, consultez Vérification des fichiers.

Sortie JSON #

La sortie JSON contient issues et stats. Pour une utilisation en local, la sortie lisible par l’utilisateur répertorie les mêmes problèmes.

Chaque problème comporte type et message. Les problèmes React peuvent comporter src ; les problèmes liés aux fichiers comportent file, et un problème missing-target comporte également locale.

Les statistiques contiennent messages, locales, missingContext, missingTranslations, orphaned, staleJsonc et staleTypes, qui valent zéro ou false lorsque les vérifications React n’ont pas été exécutées. Le nombre de langues comprend les langues cibles détectées ainsi que la langue source. Lorsque la vérification des fichiers a été exécutée, stats.files contient lockfile, sources, locales, changedSources et missingTargets. Ces données décrivent la cohérence, sans mesurer la qualité linguistique.

Exécuter la vérification en CI #

Exécutez la vérification à chaque demande de fusion (pull request ou merge request), y compris celles provenant de forks :

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

Utiliser les mêmes paramètres que pour l’extraction #

--src, --out, --types et --source-locale s’appliquent uniquement aux vérifications React. --src vaut src par défaut, et --source-locale vaut en par défaut. --out prend le pas sur le chemin de catalogue configuré, puis sur locales ; --types prend le pas sur le chemin de déclarations configuré, puis sur lingo.d.ts. Les chemins sont résolus à partir de la racine du projet. La valeur par défaut de la langue source est indépendante de la configuration de localisation. --json vaut false par défaut et s’applique aux deux types de vérifications.

Exécutez l’extraction avec ces mêmes paramètres pour remettre les données à jour. Examinez les avertissements et les différences, puis relancez la vérification et la compilation de l’application. Ne supprimez que les entrées dont l’obsolescence est confirmée, puis régénérez les déclarations.

Limites #

  • La vérification des fichiers s’effectue au niveau des fichiers. Une clé manquante dans une cible existante n’est pas signalée, sauf dans les catalogues React .jsonc.
  • Les langues regroupées dans un même catalogue partagé, comme un fichier .xcstrings, ne sont pas vérifiées. Toute modification manuelle dans ce catalogue est considérée comme une modification de la source.
  • Un dépôt passé de la CLI à la GitHub App doit supprimer .lingo/lock.json.
  • Les erreurs de configuration, comme deux sources qui aboutissent à la même cible ou un Lockfile corrompu, entraînent une sortie avec le code 1, un message sur stderr et aucune sortie JSON.
  • Les empreintes des sources sont calculées à l’octet près. Le checkout qui a exécuté lingo push et celui de la CI doivent donc utiliser les mêmes fins de ligne. Ajoutez * text=auto eol=lf à .gitattributes.

Pour les catalogues React, les cibles sont les fichiers .jsonc du répertoire du catalogue. Lorsque les motifs files correspondent au catalogue source (par exemple, locales/en.jsonc), le fichier de chaque langue cible configurée est également requis.

Seuls les avertissements d’extraction liés à un contexte manquant deviennent des problèmes de contexte. Les avertissements sur les expressions dynamiques et les informations sur les collisions ne constituent pas ici un critère d’échec exhaustif ; l’extraction elle-même impose l’échec en cas de collision. Une valeur de remplacement non vide dans la langue source peut également passer la vérification de présence sans être une traduction.

Utilisez extract --check si vous avez uniquement besoin de vérifier que les octets générés sont à jour. Conservez la validation des formats natifs et la relecture du contenu en complément de cet outil. Une vérification réussie ne garantit rien quant aux ressources Android, au rendu Markdown ou au sens des traductions au-delà des contrôles réellement effectués.