Automatiser les traductions en CI

Faites de la traduction une étape reproductible de vos livraisons, d’une révision source connue à des fichiers inspectés et aux vérifications de l’application.

Un pipeline de livraison relie déjà une révision source à un résultat utilisable. La traduction doit préserver ce lien. La tâche doit identifier la source modifiée, récupérer les fichiers cibles correspondants et fournir à l’étape suivante suffisamment d’éléments pour les accepter ou les rejeter.

Les difficultés surviennent après la première requête réussie : une personne chargée de la relecture modifie encore le contenu, un exécuteur disparaît ou une nouvelle révision du contenu source arrive avant qu’une traduction précédente soit terminée. Ce guide détaille un processus de CI capable de gérer ces situations sans publier de fichiers obsolètes ni remplacer inutilement des modifications acceptées. Les configurations YAML propres à chaque fournisseur figurent dans les exemples de configuration GitHub Actions, GitLab, Bitbucket et Buildkite.

Décider où intégrer les traductions au processus de livraison #

Utilisez la GitHub App gérée si son workflow de dépôt vous convient. Les modifications de la branche par défaut génèrent une demande de fusion de traductions ; le traitement des demandes de fusion, activé sur demande, écrit dans la branche de la demande concernée. L’approbation de l’exécution autorise le travail de traduction ; la relecture du contenu et la fusion interviennent ensuite.

Avec un agent d’exécution de la CLI, votre pipeline prend en charge l’envoi, la récupération et la livraison. Choisissez une destination adaptée à votre processus de livraison :

DestinationDécision facilitée
Artefact uniquementUne autre tâche ou une personne inspecte les résultats avant toute modification du dépôt ou de la livraison.
Branche de traduction et demande de fusionRelire séparément les modifications traduites avant leur intégration à la branche par défaut.
Branche de la demande de fusion sourceRelire la source et les traductions ensemble, dans une même modification.
Commit direct sur la branche par défautLivrer sans demande de fusion de traductions distincte lorsque les règles de la branche l’autorisent explicitement.

Pour les écritures dans le dépôt, désignez un seul agent actif par état de traduction. Sinon, deux agents d’exécution travaillant à partir de révisions sources différentes risquent de committer les fichiers et le Lockfile de manière concurrente. Prévoyez aussi des règles fondées sur la branche, le chemin ou les commits générés pour éviter que ces derniers ne déclenchent la traduction en boucle.

Établir l’état de référence dont héritera l’agent d’exécution #

Avant d’activer les exécutions récurrentes, traduisez localement un fichier source dans une langue et lancez les vérifications des ressources de l’application. Committez ensemble la configuration, la cible acceptée et .lingo/lock.json. Un checkout propre doit reproduire la même sélection de sources et la même organisation des cibles.

Les exemples des fournisseurs utilisent une version fixe de @lingo.dev/cli@1.21.0. Remplacez-la par la version actuelle de la CLI lorsque vous configurez votre workflow. Pour gérer la CLI avec les dépendances du projet, installez-la avec npm install --save-dev --save-exact @lingo.dev/cli@1.21.0 et committez package.json et package-lock.json. Utilisez ensuite npm ci et npx --no-install lingo pour exécuter la version enregistrée dans le Lockfile.

.lingo/config.json sélectionne les langues, les motifs de fichiers et le moteur de localisation. Configurez l’accès à l’organisation et au moteur de localisation dès la mise en place. Si la tâche doit initialiser ou lier un projet, utilisez les options explicites décrites dans les références Initialisation et Liaison, plutôt que de laisser une invite attendre une réponse en l’absence de toute intervention humaine.

Dans un monorepo, placez-vous dans le paquet contenant la configuration souhaitée avant d’exécuter la CLI. Les motifs positionnels restreignent les sources sélectionnées par cette configuration ; ils ne sélectionnent pas celle d’un autre paquet. Conservez ensemble l’état et les chemins d’artefacts de chaque paquet configuré indépendamment.

Injectez LINGO_API_KEY via le mécanisme de gestion des secrets de l’agent d’exécution. Il fonctionne sans connexion interactive. N’exécutez les tâches disposant d’identifiants qu’à partir de code de confiance : une branche peut modifier les scripts pour exposer la clé. Les restrictions liées aux variables protégées et aux forks doivent déterminer où la tâche s’exécute. Ne les supprimez pas pour permettre à une tâche non fiable de réussir.

Envoyer le bon type de travail #

Pour une première traduction à partir d’un état propre, demandez les fichiers cibles manquants. Dans un projet existant, terminez d’abord les mises à jour habituelles de la source pour les cibles existantes, puis récupérez et inspectez les résultats. Ajoutez ensuite les langues manquantes et effectuez le remplissage rétroactif en conservant la même révision source. Suivez Ajouter une langue avant d’exécuter cette commande :

sh
lingo push --backfill-missing --wait

Pour les modifications de la source par rapport à l’état de référence établi :

sh
lingo push --wait

Un premier envoi simple peut enregistrer l’état de la source sans la traduire. Le remplissage rétroactif fournit la tâche de création des fichiers manquants ; les envois ordinaires suivants s’appuient sur les modifications de la source pour déterminer le travail à effectuer. Un envoi à périmètre limité ou avec remplissage rétroactif n’est pas une solution universelle pour réparer les clés manquantes dans les fichiers cibles existants.

--wait attend la fin de l’exécution et télécharge les résultats terminés. Sans cette option, l’envoi rend la main après la soumission. Une attente de relecture ou une tâche de récupération distincte nécessite la procédure de préservation de l’état d’exécution en CI : avant que l’agent d’exécution ne s’arrête, conservez le pointeur spécifique non secret situé dans le répertoire personnel, le chemin absolu d’origine de la racine du projet et les états correspondants de la source, de la configuration, des cibles et du Lockfile. Restaurez-les à cette même racine et authentifiez-vous séparément avant d’utiliser lingo pull --dry-run, puis lingo pull. Si l’agent d’exécution ne peut pas recréer ce chemin, utilisez plutôt un checkout persistant disposant des autorisations nécessaires. N’archivez jamais les identifiants ni l’intégralité de ~/.lingo.

Conservez le code de sortie et les résultats signalés pour chaque cible. La CLI actuelle échoue lorsque des cibles sont signalées en échec, mais une relecture humaine peut laisser une exécution en attente de décisions. Un ancien fichier peut encore être présent alors que la nouvelle version est en attente. Terminez la relecture et récupérez le résultat avant d’autoriser la tâche de livraison à le publier.

Consultez Envoyer et Récupérer pour connaître le comportement exact des commandes. --yes passe l’étape de confirmation de la régénération forcée ; cette option n’approuve pas la relecture humaine et ne transforme pas toutes les actions en attente en travail terminé.

La CLI ignore les vérifications de mise à jour en CI. LINGO_DISABLE_UPDATE_CHECK=1 et LINGO_TELEMETRY_DISABLED=1 permettent de les contrôler explicitement au besoin, sans désactiver les échanges de traduction.

Vérifier que l’étape suivante dispose de fichiers utilisables #

Vérifiez que l’entrée attendue a bien été modifiée pour la révision source concernée. La seule présence d’un fichier est une preuve insuffisante si le checkout contient déjà une ancienne cible. Conservez les résultats téléchargés et l’état du Lockfile issus de la même opération, et indiquez clairement comme incomplètes les langues en échec ou encore en attente.

Utilisez ensuite des vérifications adaptées à la ressource :

  • Pour l’extraction React, exécutez lingo extract --check, lingo check, la vérification TypeScript du projet et la compilation réelle de l’application. Ces vérifications examinent différents aspects du résultat.
  • Pour les ressources natives, lancez la génération ou la compilation des ressources de la plateforme.
  • Pour le contenu statique, analysez les documents traduits et inspectez les liens, les variables et la syntaxe préservée.
  • Pour faire échouer une demande de fusion lorsque les traductions ne sont pas à jour, exécutez lingo check. Aucune clé API n’est nécessaire.

lingo check fonctionne au niveau des fichiers : il signale une source modifiée et un fichier cible manquant pour chaque langue configurée, et non une clé manquante dans un fichier Android, Apple, ARB ou Markdoc existant.

Vérifiez le sens de la traduction dans le cadre du processus d’acceptation choisi. Une compilation peut détecter une ressource mal formée tout en acceptant une phrase qui modifie une condition importante. Une fois les vérifications et la relecture réussies, committez ou publiez uniquement les chemins de sortie prévus. Prévoyez une sortie sans modification et laissez les vérifications requises faire échouer la tâche, plutôt que de masquer leur échec par un commit inconditionnel.

Reprendre le travail enregistré avant de lancer un travail de remplacement #

Après l’interruption d’une tâche, récupérez son identifiant d’exécution et les résultats de ses cibles. Si la traduction est terminée, récupérez ces résultats avant d’envoyer une nouvelle requête. Si une cible locale a changé pendant l’attente, résolvez le conflit de récupération en gardant la modification acceptée visible : un écrasement forcé peut supprimer précisément la correction que le workflow doit préserver.

Conservez le Lockfile pendant le diagnostic. Le supprimer modifie l’état de référence de la source pour l’exécution suivante et peut transformer une récupération ciblée en un travail différent. Inspectez les différences et relancez uniquement le périmètre encore incomplet. Récupérer une exécution de localisation interrompue détaille ce choix.

Avant de planifier la tâche, testez une attente de relecture humaine et une récupération interrompue, en plus du scénario de réussite. L’étape de livraison doit conserver le dernier état accepté et identifier la langue incomplète, plutôt que d’accepter un fichier simplement parce qu’il existe.