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.
lingo check --jsonQuelles vérifications sont effectuées #
| Vérification | Conditions d’exécution |
|---|---|
| Vérification des fichiers | .lingo/config.json contient files, ou le projet n’utilise pas React. |
| Vérifications React | Le 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.
| Cas | Problème | Correction |
|---|---|---|
| Une source correspond à son entrée dans le Lockfile et ses cibles existent | aucun | |
Aucun motif files ne correspond à un fichier | no-source-files | Corrigez les motifs files |
| Une source a changé depuis sa dernière traduction | source-changed | lingo push --wait, ou lingo pull si un push est encore en cours |
| Une source n’a aucune entrée dans le Lockfile | source-not-pushed | lingo push --wait |
| Un fichier cible manque et sa source est à jour | missing-target | lingo push --backfill-missing --wait |
| Un fichier cible manque et sa source a changé ou n’a jamais été envoyée | missing-target | lingo push --wait |
| Un fichier cible a été modifié manuellement | aucun | |
| Le Lockfile est absent et tous les fichiers cibles existent | aucun, avec une note sur stderr | |
| Le Lockfile est absent et un fichier cible manque | missing-target, avec une note sur stderr | lingo 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 #
| Type | Piste de correction à explorer |
|---|---|
missing-context | Ajoutez un contexte utile au message extrait. |
stale-jsonc | Régénérez le catalogue source et examinez-le. |
stale-types | Régénérez les déclarations et incluez-les dans la vérification des types de l’application. |
missing-translation | Examinez une clé active qui ne possède aucune valeur cible active non vide. |
orphaned | Avant 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 :
- uses: actions/checkout@v4
- run: npx @lingo.dev/cli@latest checkUtiliser 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 pushet 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.