Recette Buildkite
Traduisez des fichiers dans un pipeline Buildkite, poussez le résultat vers la branche et faites échouer les pull requests dont les traductions ne sont pas à jour.
Une étape Buildkite peut traduire les fichiers du dépôt avec la CLI Lingo.dev sur vos propres agents. La CLI soumet les fichiers source sélectionnés par votre configuration Lingo.dev et écrit les fichiers traduits dans le checkout ; votre pipeline détermine ensuite comment les livrer. Buildkite gère les agents, les secrets et l’accès au dépôt ; Lingo.dev traite les fichiers via un moteur de localisation.
Il s’agit d’une recette CI, pas d’une connexion native à Buildkite. Commencez par une seule étape de traduction sur la branche par défaut ou dans les builds de pull requests, puis examinez son premier commit. N’ajoutez le contrôle des pull requests que dans les cas où le tableau indique qu’il est adapté.
Préparer le dépôt et l’agent #
Suivez le guide de démarrage rapide de la CLI en local. Committez .lingo/config.json, les fichiers cibles acceptés et .lingo/lock.json. La configuration définit la langue source, les langues cibles, les motifs de fichiers et le moteur de localisation. Les exemples utilisent locales/en.json comme source et un fichier cible espagnol existant à l’emplacement locales/es.json. Si vous avez davantage de cibles, exécutez test -s et les vérifications JSON une fois par fichier cible, et indiquez chaque chemin cible dans les autres commandes qui mentionnent locales/es.json, ou ajoutez à l’index tout le répertoire cible, comme locales/. Le Lockfile enregistre la source comme traduite : un push ultérieur l’ignore donc, et toute cible omise du commit reste obsolète.
Créez les fichiers cibles manquants avec lingo push --backfill-missing --wait avant de mettre en place l’étape récurrente. Utilisez ensuite la commande lingo push --wait habituelle pour les modifications de la source. Le remplissage rétroactif des fichiers manquants ne corrige pas les clés manquantes dans une cible existante.
L’agent a besoin de Node.js, de npm et de Git, ainsi que d’un accès réseau au registre npm et à Lingo.dev. Les identifiants d’accès au dépôt utilisés par l’agent pour le checkout, par exemple une clé de déploiement, doivent aussi autoriser les push vers la branche sur laquelle l’étape écrit.
Stockez la clé API Lingo.dev sous la forme d’un secret Buildkite nommé LINGO_API_KEY. La CLI ne lit que ce nom ; elle ignore toute variable LINGODOTDEV_API_KEY de l’ancienne CLI, qu’il faut donc renommer. Ne chargez le secret que dans l’étape de traduction. La clé secrets: de l’étape nécessite un agent Buildkite 3.106.0 ou ultérieur, exécuté dans le cluster qui contient le secret ; les agents plus anciens font échouer le pipeline. Sur les agents plus anciens ou hors cluster, supprimez secrets: et exportez plutôt LINGO_API_KEY pour cette étape depuis un hook environment de l’agent ou votre plugin de gestion des secrets.
Laissez l’option Autoriser les builds provenant de dépôts forkés tiers désactivée dans les paramètres GitHub du pipeline. Les builds des pull requests d’un fork utilisent le fichier pipeline.yml propre à ce fork, qui peut ajouter une étape lisant le secret ; aucun if: dans votre fichier ne peut l’en empêcher. Ajoutez également une politique d’accès au secret pour que seuls les builds de ce pipeline puissent le lire.
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 la version via les dépendances et le Lockfile de votre projet, suivez le guide de configuration CI.
Traduire et pousser le résultat vers la branche #
Cette étape traduit chaque modification qui arrive sur la branche par défaut et pousse le résultat vers cette même branche. Elle suppose que le remplissage rétroactif initial a été committé et que la relecture humaine du moteur est désactivée, pour que la traduction se termine en une seule étape. Ajoutez-la à .buildkite/pipeline.yml :
steps:
- label: "Translate"
if: build.branch == pipeline.default_branch && build.pull_request.id == null
concurrency: 1
concurrency_group: "lingo-translations"
# secrets: needs Buildkite agent 3.106.0 or later.
secrets:
- LINGO_API_KEY
command: |
# 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:refs/heads/$${BUILDKITE_BRANCH}"--wait fait attendre l’étape jusqu’à la fin de l’exécution et écrit les fichiers traduits dans le checkout. Sans cette option, lingo push se contente de soumettre l’exécution puis se termine : l’étape ne trouve donc rien à committer. lingo push --wait renvoie un code de sortie non nul lorsqu’une cible échoue, ce qui arrête l’étape avant le commit. Si rien n’a changé, la commande affiche "Rien à pousser", le diff des modifications dans l’index est vide et l’étape se termine sans commit.
Buildkite effectue le checkout d’un seul commit plutôt que d’une branche : le push précise donc le nom de la branche. $$ laisse le shell développer BUILDKITE_BRANCH lors de l’exécution de l’étape ; avec un seul $, Buildkite inscrirait le nom de la branche dans le texte de la commande au moment de charger le pipeline. concurrency et concurrency_group exécutent une seule traduction à la fois. Si la branche a avancé pendant la traduction, Git rejette le push ; le build du commit plus récent se charge de la traduction.
L’étape ne tourne pas en boucle. Buildkite ignore les builds des commits dont le message contient [skip ci]. Sans cette indication, le build suivant ne trouverait rien à pousser, car le fichier .lingo/lock.json committé enregistre déjà la nouvelle source.
Pousser directement vers la branche par défaut supprime la relecture d’une pull request de traduction : choisissez donc cette politique de branche en connaissance de cause. Pour relire les traductions au préalable, poussez plutôt vers une branche distincte telle que lingo/translations et ouvrez une pull request avec les outils de votre fournisseur Git.
Traduire dans les builds de pull requests #
Pour traduire les modifications de la source de chaque pull request sur sa propre branche, utilisez cette étape à la place de celle de la branche par défaut. Elle repose sur les mêmes hypothèses. Son if: ignore les pull requests provenant de forks, car l’étape ne peut pas pousser vers la branche d’un fork.
L’étape nécessite deux réglages dans les paramètres GitHub du pipeline. Activez Lancer un build à l’ouverture ou à la mise à jour d’une pull request. Désactivez Lancer des builds de branches, ou limitez cette option à la branche par défaut. Lorsque les builds de branches sont activés, un push vers une branche de pull request peut lancer un build sans les informations de la pull request. L’étape ignore ce build : rien n’est donc traduit et rien n’échoue.
Le if: ne protège pas LINGO_API_KEY. Buildkite le lit depuis le fichier pipeline.yml propre à la pull request, et un fork peut modifier ce fichier : les builds de forks doivent donc rester désactivés, comme l’indique la configuration. Une pull request provenant d’une branche du dépôt peut aussi modifier ce fichier ; toute personne pouvant pousser une branche peut donc lire la clé via cette étape. N’utilisez cette étape que si toutes les personnes disposant d’un accès en écriture sont autorisées à détenir la clé.
steps:
- label: "Translate pull request"
if: build.pull_request.id != null && build.pull_request.repository.fork != true
# secrets: needs Buildkite agent 3.106.0 or later.
secrets:
- LINGO_API_KEY
command: |
# 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 "Update translations"
git push origin "HEAD:refs/heads/$${BUILDKITE_BRANCH}"Le message de commit ne contient volontairement pas [skip ci]. Buildkite lance un build du commit de traduction, l’étape s’exécute à nouveau, ne trouve rien à pousser et se termine sans commit : la boucle s’arrête donc après un seul build supplémentaire. Ce build attribue un statut au dernier commit de la pull request. Avec [skip ci], le dernier commit n’aurait aucun build Buildkite, et un contrôle de statut Buildkite obligatoire bloquerait la fusion.
Les identifiants utilisés par l’agent pour le checkout doivent autoriser les push vers les branches de pull requests. Si la branche a avancé pendant la traduction, Git rejette le push et l’étape échoue ; le build du commit plus récent se charge de la traduction. Deux push rapprochés lancent donc deux traductions, toutes deux facturées. Activez Annuler les builds intermédiaires dans les paramètres du pipeline pour qu’un push plus récent annule le build précédent. Une traduction déjà soumise par le build précédent n’est pas annulée.
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 pas d’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 secret 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 l’ancienne CLI.
La commande vérifie les fichiers, pas les clés : une cible modifiée à la main passe le contrôle, 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 poussée ne fait donc pas échouer le contrôle, et la commande le signale sur stderr. Committez le Lockfile écrit par lingo push.
Ajoutez cette étape à .buildkite/pipeline.yml lorsque le tableau ci-dessous indique que le contrôle est adapté. Elle s’applique à une configuration sans aucune des deux étapes de traduction précédentes : chaque exemple présenté ici constitue donc une liste steps: complète pour une configuration donnée. Intégrez l’étape de l’exemple à votre liste steps: existante plutôt que d’ajouter une deuxième clé steps: :
steps:
- label: "Check translations"
if: build.pull_request.id != null
command:
# lingo check needs CLI 1.20.0 or newer.
- npx -y @lingo.dev/cli@1.21.0 checkLe contrôle convient à une configuration où les traductions sont committées en même temps que la modification de la source :
| Où s’exécute la traduction | Contrôle sur chaque pull request |
|---|---|
Les équipes de développement exécutent lingo push --wait et committent le résultat avant d’ouvrir la pull request | Oui. Il fait échouer une pull request dont la source a changé sans être traduite. |
| L’étape de traduction pousse vers la branche par défaut après la fusion | Non. Les pull requests de fonctionnalités modifient les sources avant la traduction, par conception. |
| L’étape de pull request committe sur la branche de la pull request | Non. Dans le build qui traduit, le contrôle voit le commit avant la traduction et échoue. La nouvelle exécution de l’étape sur le commit de traduction, qui ne trouve rien à pousser, montre qu’aucune source n’a changé depuis .lingo/lock.json. |
Les empreintes des sources sont exactes à l’octet près. Faites en sorte que le checkout ayant exécuté lingo push et le checkout CI utilisent les mêmes fins de ligne, par exemple avec * text=auto eol=lf dans .gitattributes.
Adapter l’étape #
Pour un monorepo, exécutez la CLI depuis le package qui contient .lingo/config.json, par exemple avec cd apps/web au début de la commande, et ajoutez à l’index les fichiers cibles et le Lockfile de ce package. Les packages indépendants conservent chacun leur propre Lockfile et peuvent utiliser des moteurs de localisation différents.
Si le moteur de localisation envoie le travail en relecture humaine, lingo push --wait renvoie le code de sortie 0 après avoir écrit uniquement les fichiers terminés. Ne committez pas ce résultat partiel comme s’il était complet. Ajoutez la procédure de conservation de l’état d’exécution en CI et récupérez le reste avec Récupérer sur le même agent une fois la relecture terminée.
Rétablir le fonctionnement de l’étape et la retirer #
Appuyez-vous sur l’erreur pour déterminer la prochaine action : réparer l’installation des packages, fournir le secret, terminer la relecture, résoudre un conflit lors de la récupération ou réessayer le traitement des cibles en échec après en avoir corrigé la cause. Gardez les codes de sortie non nuls visibles ; || true masque la cause.
Supprimez l’étape ou son déclencheur pour arrêter les nouveaux builds. Lors de l’annulation d’un build, examinez séparément toute traduction déjà soumise. Supprimez le secret LINGO_API_KEY et l’accès en écriture de l’agent lorsque vous retirez la recette.