Recette pour Bitbucket Pipelines

Traduisez les fichiers dans Bitbucket Pipelines, committez les résultats dans le dépôt et faites échouer les pull requests dont les traductions ne sont pas à jour.

Utilisez un pipeline Bitbucket pour traduire les fichiers source sélectionnés dans votre configuration Lingo.dev. La CLI soumet le travail et télécharge les fichiers cibles ; votre pipeline détermine comment les conserver et les livrer. Cette recette commence par un pipeline personnalisé à déclenchement manuel, pour vous permettre de vérifier une traduction avant de planifier des exécutions récurrentes.

La connexion passe par l’appel API de votre runner, et non par un connecteur natif de compte Bitbucket. L’écriture dans le dépôt et la création de pull requests nécessitent des autorisations Bitbucket distinctes.

Préparer un catalogue fonctionnel #

Suivez le guide de démarrage rapide de la CLI en local, puis committez .lingo/config.json, les fichiers cibles vérifiés et .lingo/lock.json. Cette configuration doit contenir les langues source et cibles, le moteur de localisation et les motifs de sélection des fichiers.

L’exemple utilise locales/en.json et un fichier espagnol existant à l’emplacement locales/es.json comme unique cible. Si vous avez plusieurs cibles, exécutez test -s et les vérifications JSON pour chaque fichier cible, et indiquez tous les chemins cibles dans les autres commandes qui mentionnent locales/es.json. Le Lockfile enregistre la source comme traduite : un push ultérieur l’ignore donc, et une cible absente de l’artefact reste obsolète. Créez les fichiers cibles manquants avec lingo push --backfill-missing --wait avant d’adopter la commande ci-dessous pour traiter les modifications régulières de la source. Un push classique traite les modifications ultérieures de la source ; le remplissage rétroactif des fichiers manquants ne rétablit pas les clés manquantes dans une cible existante.

Enregistrez LINGO_API_KEY comme variable de dépôt sécurisée. La CLI ne lit que ce nom ; elle ignore les variables LINGODOTDEV_API_KEY de la CLI précédente : renommez donc la vôtre. Exécutez le pipeline sur du code de confiance et laissez le traçage shell désactivé lors de la manipulation des identifiants. Sécuriser une variable ne rend pas son exposition à des scripts arbitraires issus d'une pull request sans risque.

Les exemples fixent la version de la CLI à 1.21.0. lingo check vérifie les fichiers de traduction à partir de la version 1.20.0 de la CLI. Pour gérer cette version via les dépendances et le Lockfile de votre projet, suivez le guide de configuration de la CI.

Traduire et conserver le résultat #

Ajoutez ce pipeline personnalisé à bitbucket-pipelines.yml :

yaml
image: node:22

pipelines:
  custom:
    translate-catalog:
      - step:
          name: Translate and inspect
          script:
            # Replace 1.21.0 with the current CLI version.
            - npx -y @lingo.dev/cli@1.21.0 push --wait
            - test -s locales/es.json
            - node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
            - git diff -- locales/es.json .lingo/lock.json
          artifacts:
            - locales/es.json
            - .lingo/lock.json

Assurez-vous que le runner peut télécharger la CLI depuis npm. Adaptez les chemins des fichiers à votre configuration.

Vérifiez les identifiants de l’organisation et du moteur dans le fichier .lingo/config.json committé. Committez une petite modification de la source anglaise, puis exécutez translate-catalog sur cette branche de confiance. Examinez le résultat de l’exécution et le diff, puis téléchargez l’artefact et comparez l’entrée espagnole modifiée à la révision source. Chargez le catalogue dans l’application pour vérifier les variables et le rendu.

La vérification de l’existence des fichiers et l’analyse JSON permettent de détecter les résultats manquants ou mal formés. Elles ne permettent toutefois pas de distinguer un ancien fichier valide de la nouvelle traduction demandée. Si le moteur de localisation exige une relecture humaine, terminez cette relecture et récupérez les résultats finalisés avant d’accepter l’artefact.

Conserver l’état de soumission et de récupération #

L'envoi est asynchrone par défaut. push --wait attend la fin de l'exécution et écrit les fichiers traduits dans le checkout. Sans --wait, lingo push se contente de soumettre l'exécution, puis se termine : la commande suivante ne trouve donc aucun nouveau fichier à conserver ou à committer. L'attente d'une relecture humaine peut toutefois nécessiter une étape de récupération ultérieure.

Avant une attente de relecture ou une étape de récupération distincte, ajoutez la procédure de conservation de l’état d’exécution en CI. Après la soumission, exportez le pointeur concerné et le chemin absolu d’origine de la racine du projet, même si une validation ultérieure échoue. Conservez .lingo-ci/run.json, .lingo-ci/project-root.txt, .lingo/config.json, locales/en.json, le fichier cible et le Lockfile sous forme d’artefacts à accès restreint, avec une durée de conservation suffisante pour la relecture. Veillez à laisser visible l’échec de l’étape d’origine et n’archivez jamais l’intégralité de ~/.lingo ni les identifiants.

Pour récupérer les résultats, restaurez la même révision et l’état des fichiers conservés au chemin absolu enregistré pour la racine du projet. Restaurez uniquement ce pointeur, fournissez les identifiants séparément et utilisez Pull avec --dry-run avant de collecter les résultats. Si une étape ultérieure du pipeline ne peut pas recréer ce chemin, utilisez plutôt un runner persistant et autorisé pour la soumission comme pour la récupération. Résolvez les conflits de fichiers locaux en connaissance de cause : forcer un pull peut supprimer les modifications de la personne chargée de la relecture.

Choisir comment transmettre les résultats au dépôt #

Un artefact suffit lorsqu’une personne ou une tâche de publication ultérieure doit vérifier les résultats avant leur livraison. Conservez ensemble les fichiers traduits et le Lockfile issus de la même opération terminée.

Pour soumettre une mise à jour du dépôt à relecture, envoyez les modifications vers une branche de traduction, puis ouvrez une pull request dans Bitbucket ou via son API documentée. Une étape peut envoyer des modifications vers son propre dépôt via le origin par défaut, sans identifiant supplémentaire, comme le montre la section suivante. N'ajoutez une clé SSH de dépôt ou un jeton d'accès que si les autorisations de branche bloquent cet envoi, ou pour créer la pull request via l'API, qui nécessite un accès en écriture aux pull requests. Configurez l'identité du bot de l'équipe, n'ajoutez à l'index que les chemins cibles connus et .lingo/lock.json, et terminez l'étape si le diff de l'index est vide. Utilisez des noms de branche distincts ou réutilisez les branches de façon délibérée pour éviter que les exécutions simultanées ne s'écrasent mutuellement.

Un commit direct applique les mêmes vérifications des résultats et limite de la même façon les fichiers ajoutés à l’index, mais envoie les modifications vers la branche de confiance explicitement prévue. La livraison directe sur la branche par défaut supprime l’étape de relecture de la pull request de traduction ; elle doit donc résulter d’un choix délibéré dans votre politique de gestion des branches. Dans les deux cas, vérifiez le résultat dans l’application.

Conservez la clé API Lingo.dev séparément des identifiants du dépôt. Elle doit rester dans l’environnement du processus de traduction, jamais dans une configuration de dépôt distant Git, un fichier committé ou un artefact de sortie. Ajoutez des chemins explicites à l’index plutôt que git add . pour éviter d’inclure des fichiers du runner sans rapport avec la traduction.

Committer les traductions sur la branche #

Ce pipeline de branche traduit chaque modification qui arrive sur main et committe le résultat sur main. Il suppose que le remplissage rétroactif initial a été committé et que la relecture humaine du moteur est désactivée, afin que la traduction se termine en une seule étape. Ajoutez sa section branches sous la même clé pipelines que le pipeline personnalisé. Le fichier complet se présente alors ainsi :

yaml
image: node:22

pipelines:
  custom:
    translate-catalog:
      - step:
          name: Translate and inspect
          script:
            - npx -y @lingo.dev/cli@1.21.0 push --wait
            - test -s locales/es.json
            - node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
            - git diff -- locales/es.json .lingo/lock.json
          artifacts:
            - locales/es.json
            - .lingo/lock.json
  branches:
    main:
      - step:
          name: Translate and commit
          auth:
            system:
              scopes:
                - read:git:bitbucket
                - write:git:bitbucket
          script:
            # Replace 1.21.0 with the current CLI version.
            - npx -y @lingo.dev/cli@1.21.0 push --wait
            - test -s locales/es.json
            - node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
            - git add -- locales/es.json .lingo/lock.json
            - if git diff --cached --quiet; then exit 0; fi
            - git config user.name "Localization bot"
            - git config user.email "localization@example.com"
            - git commit -m "[skip ci] Update translations"
            - git push origin "HEAD:$BITBUCKET_BRANCH"

lingo push --wait se termine avec un code de sortie non nul lorsqu'une cible échoue ; l'étape s'arrête donc avant le commit. Si rien n'a changé, la commande affiche « Rien à envoyer », le diff de l'index est vide et l'étape se termine sans commit.

Pipelines configure le dépôt distant origin pour qu’une étape puisse envoyer des modifications vers son propre dépôt sans identifiant supplémentaire. Le bloc auth de l’étape accorde à son jeton intégré le droit d’effectuer un push Git. À compter du 30 avril 2027, Bitbucket n’accordera plus ce droit aux étapes dépourvues de bloc auth. Les agents d’exécution auto-hébergés doivent être en version 6.1.0 ou ultérieure pour utiliser auth. Si une restriction de branche sur main bloque le push, ajoutez main comme branche source dans les droits d’écriture de Pipelines définis par cette restriction, ou fournissez à l’étape une clé SSH ou un jeton d’accès disposant de droits d’écriture, comme décrit dans le guide Bitbucket pour envoyer des modifications vers le dépôt.

L'étape ne tourne pas en boucle. La présence de [skip ci] dans le message de commit empêche Bitbucket de démarrer un pipeline pour le commit de traduction. Sans cela, l'exécution suivante ne trouverait rien à envoyer, car le .lingo/lock.json committé enregistre déjà la nouvelle source. Si la branche a évolué pendant la traduction, Git rejette l'envoi ; le pipeline du commit plus récent traduit alors les modifications.

Adapter les déclencheurs et les chemins des paquets #

N’ajoutez des déclencheurs automatiques de branche ou de pull request qu’après avoir décidé quel code source peut accéder aux identifiants et quelle branche peut recevoir des écritures. Un fork peut ne disposer ni des secrets ni d’une destination accessible en écriture ; ne contournez pas ce problème en exécutant son code non fiable avec des identifiants privilégiés.

Les commits générés ne doivent pas déclencher la traduction en boucle. Sélectionnez les chemins source pertinents et les branches de confiance, appliquez une règle adaptée aux commits générés et conservez l’arrêt du traitement en l’absence de modifications. Une source inchangée peut tout à fait ne produire aucun diff.

Pour une configuration située à apps/web/.lingo/config.json, exécutez la CLI depuis apps/web. Les chemins des artefacts du pipeline restent soumis aux règles de Bitbucket : ils sont relatifs à la racine du dépôt. Utilisez donc des chemins tels que apps/web/locales/es.json et apps/web/.lingo/lock.json. Changer le répertoire de travail de la CLI ne modifie pas cette convention.

Faire échouer les pull requests dont les traductions ne sont pas à jour #

lingo check compare chaque source configurée à .lingo/lock.json et exige la présence de tous les fichiers cibles. La commande renvoie le code de sortie 1 si une source a changé depuis sa dernière traduction, si une source n’a aucune entrée dans le Lockfile, si un fichier cible manque ou si aucun fichier source ne correspond aux motifs files. Elle ne nécessite ni clé API ni variable de dépôt et n’écrit rien. Hormis la télémétrie de la CLI, que DO_NOT_TRACK=1 désactive, elle n’effectue aucun appel réseau ; l’exemple npx télécharge toutefois la CLI depuis npm avant de lancer la vérification. Elle remplace le contrôle --frozen de la CLI précédente.

La commande vérifie les fichiers, pas les clés : une cible modifiée à la main passe la vérification, et une clé manquante dans une cible existante n’est pas signalée, sauf dans les catalogues React .jsonc. Sans .lingo/lock.json, elle ne peut pas détecter les modifications de la source : une source modifiée ou jamais envoyée par push ne fait donc pas échouer la vérification, et la commande le précise sur stderr. Committez le Lockfile écrit par lingo push.

Ce contrôle bloquant s'utilise dans une configuration sans le pipeline de branche présenté plus haut ; le tableau ci-dessous explique pourquoi. Ajoutez une section pull-requests sous pipelines, à côté de custom si vous conservez le pipeline manuel. À lui seul, le fichier se présente ainsi :

yaml
image: node:22

pipelines:
  pull-requests:
    "**":
      - step:
          name: Check translations
          script:
            # lingo check needs CLI 1.20.0 or newer.
            - npx -y @lingo.dev/cli@1.21.0 check

Ce contrôle bloquant convient à une configuration où les traductions sont committées avec la modification de la source :

Où s'exécute la traductionContrôle bloquant sur chaque pull request
Les équipes de développement exécutent lingo push --wait et committent le résultat avant d'ouvrir la pull requestOui. Il fait échouer une pull request dont la source a changé sans traduction correspondante.
Le pipeline de branche committe sur main après la fusionNon. Les pull requests de fonctionnalité modifient les sources avant leur traduction : c'est le fonctionnement prévu.

Les empreintes des sources reflètent leur contenu exact, octet par octet. Assurez-vous que le checkout ayant exécuté lingo push et le checkout de la CI utilisent les mêmes fins de ligne, par exemple avec * text=auto eol=lf dans .gitattributes. Conservez également les vérifications des ressources de l'application.

Récupérer les résultats manquants ou arrêter le travail #

En cas de résultats manquants, vérifiez les fichiers source sélectionnés, l’état de référence, la couverture des cibles, la disponibilité des variables sécurisées, l’état de la relecture et les échecs signalés. Récupérez l’exécution enregistrée avant d’envisager une nouvelle soumission. Avant de procéder au remplissage rétroactif des cibles manquantes dans un projet existant, terminez les mises à jour standard de ses cibles existantes, puis récupérez-les et vérifiez-les. Maintenez ensuite la révision source inchangée pendant le remplissage rétroactif. Suivez Ajouter une langue pour respecter cet ordre. N’utilisez la régénération forcée que si vous souhaitez remplacer le texte accepté sélectionné ; la section récupération après un échec d’exécution explique comment demander une nouvelle tentative sans forcer le remplacement.

Désactivez le déclencheur du pipeline pour empêcher le lancement de nouvelles tâches. Lorsque vous annulez le runner, vérifiez séparément toute exécution déjà soumise au serveur. Supprimez les variables API inutilisées et les droits d’écriture du fournisseur lorsque vous cessez d’utiliser cette recette.