Dépannage de la CLI

Résolvez les problèmes de sélection de fichiers, de référence, de récupération des résultats et de catalogue sans supprimer d’abord les données d’état utiles.

Pendant le diagnostic d’un échec, gardez à portée de main la version installée, la commande, le répertoire de travail, l’erreur et les chemins concernés. Masquez les données d’authentification avant de partager les journaux : les diagnostics de démarrage et d’échec peuvent contenir les arguments argv bruts.

Aucun fichier source ne correspond #

Repérez le .lingo/config.json le plus proche. Une commande exécutée dans un sous-répertoire peut utiliser le projet d’un répertoire parent. Vérifiez include avant pattern, car même une inclusion vide prend le pas sur ce dernier. Les exclusions s’appliquent à chaque entrée séparément ; une autre entrée peut donc toujours sélectionner un fichier.

Utilisez une syntaxe de correspondance prise en charge, comme docs/en/**/*, placez les motifs du shell entre guillemets et vérifiez quels suffixes sont pris en charge. YAML exige de préciser explicitement yaml, yaml-root-key ou yaml-openapi ; Android XML exige android. Pour un fichier .txt, .csv ou .properties, le motif doit se terminer par son extension, ou il faut utiliser "format": "txt", "format": "csv" ou "format": "properties" ; un motif large comme docs/en/**/* ignore ce fichier, tandis qu’une entrée txt, csv ou properties ignore tous les fichiers qui n’ont pas cette extension. Préciser explicitement un format ne permet pas d’accepter toutes les extensions.

La sortie a été écrite au mauvais endroit #

Lisez les avertissements relatifs au calcul des chemins et comparez la destination avec le chargeur de votre application. Si aucun segment correspondant à la langue source n’est reconnu, définissez targetPath et sourceRoot plutôt que de compter sur le mécanisme de repli qui insère la langue. Gardez les cibles hors du périmètre de recherche des sources et examinez les collisions.

Déplacer les fichiers ne suffit pas à mettre à jour la référence. XCStrings utilise volontairement un seul catalogue source partagé ; il ne suit pas l’organisation habituelle par langue. Consultez les chemins de sortie.

Une option n’a aucun effet #

Les clés inconnues à la racine ou dans les entrées de fichiers déclenchent un avertissement et sont ignorées. Vérifiez leur orthographe et les options réellement prises en charge par le gestionnaire sélectionné. Les paramètres de chemin du catalogue ne mettent pas à jour les motifs de push, et extract et check utilisent chacun, indépendamment, en comme langue source par défaut.

L’évaluation sur votre machine utilise l’exécutable lingo.config.ts, et non le JSON du projet. Une option de protection JSON ne s’applique pas nécessairement à Markdown ou à un autre format.

Un artefact de référence est manquant #

L’artefact source précédent désigné par le hachage du Lockfile doit exister sur votre machine ou sur le serveur. Examinez l’entrée indiquée et récupérez des octets dont la validité est établie ou une référence cohérente. N’inventez pas de hachage et n’effacez pas l’intégralité du Lockfile pour masquer l’erreur.

En l’absence de données d’état, un premier push simple stocke les octets de la source ; un remplissage rétroactif est nécessaire pour les cibles ordinaires manquantes. La section Lockfile et cache explique de quel enregistrement l’opération a besoin.

Pull signale un conflit #

Exécutez lingo pull --dry-run pour examiner les décisions d’écriture. Une cible qui diffère de la sortie du serveur, des octets enregistrés lors du push et du hachage du Lockfile bloque les écritures. La committer ne change pas le résultat de la comparaison.

Conservez la modification et réconciliez-la avec les autres versions, restaurez une version connue ou ne choisissez le forçage que si vous souhaitez délibérément remplacer la cible. Ne modifiez pas les cibles pendant push --wait, qui ne revérifie pas les conflits comme le fait pull.

Le travail a échoué ou reste incomplet #

Examinez les erreurs pour chaque cible et distinguez le travail en attente, la relecture, les échecs et les sorties manquantes. En cas d’échec d’une exécution, push --wait et pull se terminent avec un code de sortie non nul après avoir écrit les documents terminés ; vérifiez l’état et les fichiers réellement présents.

Lorsque toutes les cibles inachevées attendent une relecture humaine, push --wait et pull cessent d’attendre et le signalent. Les documents dont toutes les langues sont terminées peuvent être récupérés ; exécutez à nouveau lingo pull une fois que les personnes chargées de la relecture ont terminé. Un nouveau push ne débloque pas une attente de relecture.

Si l’exécution a échoué, corrigez la cause signalée et répétez la commande adaptée au travail concerné. Pour les mises à jour ordinaires des sources, utilisez lingo push --wait avec la source inchangée et la référence conservée. Pour les fichiers cibles manquants, répétez le remplissage rétroactif uniquement une fois les cibles existantes à jour, en suivant Ajouter une langue. Il n’est pas nécessaire de modifier la source, d’utiliser une option de forçage ou de supprimer des données d’état pour simplement demander une nouvelle tentative.

Push affiche l’identifiant de la tâche qu’il soumet ou à laquelle il se rattache. Si les résultats du push précédent n’ont jamais été récupérés et que la demande est inchangée, push réutilise cette demande : une tâche encore en cours conserve son identifiant, tandis qu’une tâche en échec est remplacée par une nouvelle. Conservez l’identifiant de la tâche en échec et vérifiez que la prochaine ligne Job affichée contient un identifiant différent. Cela indique une nouvelle soumission, pas une traduction réussie : examinez les résultats pour chaque cible, récupérez la sortie et relisez les différences. Gardez les cibles locales inchangées pendant --wait ; effectuez séparément un push puis un pull avec vérification des conflits si vous devez protéger les modifications locales.

Si le client installé renvoie la même tâche en échec, cessez de répéter les soumissions et envoyez un e-mail à support@lingo.dev. Indiquez la version de la CLI, la commande sans données sensibles, les identifiants d’exécution précédents et ceux renvoyés, la révision de la source, les langues et chemins concernés, les horodatages et l’erreur sans données sensibles. N’incluez aucune donnée d’authentification, aucun texte source privé ni aucun fichier brut contenant des données d’authentification dans le message. Conservez le pointeur d’exécution local et le Lockfile pendant l’analyse de l’échec.

Supprimer le pointeur d’exécution n’est pas un moyen fiable de demander une nouvelle traduction ; tant que les résultats d’un push n’ont pas été récupérés, le pointeur conserve l’identité de la demande et empêche les soumissions en double. Si aucune exécution n’est trouvée, vérifiez la machine, le chemin absolu de la racine du projet et si un autre push a remplacé le pointeur.

Les vérifications du catalogue échouent #

Effectuez l’extraction avec la même langue et les mêmes chemins que pour check. Examinez les avertissements concernant les appels dynamiques ou déstructurés avant de supprimer les entrées orphelines. Un fichier cible manquant n’est signalé que lorsque les motifs files correspondent au catalogue source ; sinon, comparez les langues attendues aux fichiers existants.

Ne nettoyez que les suppressions intentionnelles, régénérez les déclarations, puis exécutez check et compilez l’application. status a été déplacé vers check ; les noms de services internes ne sont pas des commandes exécutables.

Avant toute suppression #

Purge affiche un aperçu de la suppression des fichiers cibles. Les filtres de fichiers et de langues limitent la suppression aux cibles sélectionnées et à leurs entrées dans le Lockfile ; une purge sans filtre supprime l’intégralité du Lockfile. Les catalogues XCStrings partagés sont ignorés. Utilisez purge lorsque la suppression est bien l’objectif. La plupart des opérations de récupération nécessitent une correction ciblée, tout en conservant les formulations acceptées et les données d’état récupérables.