Procédure CI avec GitHub Actions

Exécutez la traduction dans une tâche GitHub Actions de confiance, examinez ses artefacts, puis ajoutez la livraison par pull request lorsque le résultat est prêt.

Exécutez la CLI Lingo.dev dans GitHub Actions lorsque la traduction doit s’appuyer sur les déclencheurs et les vérifications de votre pipeline existant. Le runner lit la configuration de votre dépôt, soumet les modifications des sources et télécharge les fichiers traduits. Vous décidez si ces fichiers restent des artefacts ou font l’objet d’une pull request.

Cette procédure commence par un déclenchement manuel et un accès au dépôt en lecture seule. Après avoir examiné un message modifié, vous pouvez ajouter les autorisations d’écriture nécessaires à une pull request de traduction. La GitHub App native offre une autre approche : un traitement géré du dépôt, sans cette procédure de runner.

Préparer le dépôt #

Suivez le guide de démarrage rapide de la CLI en local avec un fichier source et une langue cible. Faites un commit de .lingo/config.json, du fichier cible examiné et de .lingo/lock.json. La configuration définit le moteur de localisation, les langues source et cibles, ainsi que les motifs de sélection des fichiers. Le Lockfile enregistre l’état de référence pour les modifications ultérieures des sources.

Pour l’exemple ci-dessous, configurez locales/en.json comme source et l’espagnol comme langue cible afin de produire locales/es.json. La première cible manquante est créée avec lingo push --backfill-missing --wait ; les modifications ultérieures de la source utilisent lingo push --wait. Le remplissage rétroactif sélectionne les fichiers cibles manquants : il ne permet donc pas de rétablir les clés manquantes dans un fichier existant.

Ajoutez LINGO_API_KEY aux secrets Actions du dépôt ou de l’environnement. Ce secret donne accès à Lingo.dev, indépendamment des autorisations du dépôt GitHub. N’exécutez la tâche utilisant ces identifiants que sur du code de confiance. En particulier, n’utilisez pas pull_request_target pour faire un checkout de la révision de tête d’une pull request non fiable et l’exécuter avec ce secret.

L’exemple fixe la version de la CLI. Pour la gérer via les dépendances et le Lockfile de votre projet, suivez le guide de configuration CI.

Obtenir un artefact de traduction #

Enregistrez cet exemple sous .github/workflows/translate.yml. Il utilise Node.js 22.

yaml
name: Translate catalog
on:
  workflow_dispatch:
permissions:
  contents: read
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Translate and download
        # Replace 1.21.0 with the current CLI version.
        run: npx -y @lingo.dev/cli@1.21.0 push --wait
        env:
          LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}
      - name: Inspect expected output
        run: |
          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
      - uses: actions/upload-artifact@v4
        with:
          name: translated-catalog
          include-hidden-files: true
          path: |
            locales/es.json
            .lingo/lock.json

Vérifiez les identifiants de l’organisation et du moteur dans le fichier .lingo/config.json enregistré dans un commit. Apportez une modification à la source anglaise, faites-en un commit, puis déclenchez le workflow depuis cette branche de confiance. Vérifiez le résultat de l’exécution et le diff dans le journal de la tâche, puis téléchargez l’artefact et retrouvez l’entrée espagnole correspondant à votre modification. Chargez-la dans l’application et vérifiez son sens et ses variables.

Le téléversement inclut les fichiers cachés afin de conserver .lingo/lock.json. Limitez la liste des chemins à la cible prévue et au Lockfile ; ne l’élargissez pas aux identifiants ni à d’autres fichiers cachés privés.

Les vérifications du shell confirment la présence des fichiers et la validité de la syntaxe JSON. Un ancien fichier cible peut satisfaire ces deux vérifications : il est donc important d’examiner l’entrée modifiée. Si le moteur de localisation exige une relecture humaine, l’exécution peut encore être en attente d’une intervention après la fin de la commande. Avant d’utiliser cette politique sur un runner éphémère, ajoutez la procédure de conservation de l’état d’exécution en CI. Après la soumission, exportez le pointeur de l’exécution concernée et le chemin absolu d’origine de la racine du projet, puis téléversez .lingo-ci/run.json, .lingo-ci/project-root.txt, .lingo/config.json, locales/en.json, la cible et le Lockfile sous forme d’artefacts à accès restreint. Utilisez if: always() pour les étapes d’export et de téléversement afin qu’un échec de vérification ultérieur ne fasse pas perdre un état récupérable ; si le pointeur manque, il faut examiner la soumission, pas en inventer un.

Après la relecture, restaurez exactement cette révision et cet état des fichiers au chemin absolu enregistré pour la racine du projet, restaurez le pointeur, authentifiez-vous séparément et utilisez Récupérer avec vérification des conflits. Si un autre runner ne peut pas recréer ce chemin, effectuez plutôt la soumission et la récupération sur un runner persistant autorisé. Ne considérez pas l’ancienne cible du premier artefact comme la traduction terminée.

push --wait attend et télécharge les résultats terminés disponibles. Sans --wait, la commande push se termine normalement après la soumission. Des tâches distinctes de soumission et de récupération nécessitent le même export et la même restauration de l’état d’exécution ; copier uniquement le Lockfile ne suffit pas. Conservez ensemble les cibles téléchargées et le Lockfile issus de la même opération terminée, et n’archivez jamais l’intégralité de ~/.lingo.

Livrer une pull request #

Une fois l’artefact examiné avec succès, accordez à la tâche les autorisations contents: write et pull-requests: write. La politique du dépôt doit également autoriser Actions à créer des pull requests. GITHUB_TOKEN autorise ces opérations GitHub ; conservez LINGO_API_KEY pour la traduction.

Configurez une identité Git conforme à la politique de votre équipe concernant les bots. Ajoutez ensuite, après la validation du résultat, une étape qui prépare uniquement la cible attendue et le Lockfile pour le commit :

bash
git add locales/es.json .lingo/lock.json
git diff --cached --quiet && exit 0
branch="lingo/translations-${GITHUB_RUN_ID}"
git switch -c "$branch"
git commit -m "chore: update translations"
git push origin "$branch"
gh pr create --fill --base "$GITHUB_REF_NAME" --head "$branch"

Les runners hébergés par GitHub incluent la CLI GitHub. Fournissez GH_TOKEN à cette étape à partir de secrets.GITHUB_TOKEN. Cette séquence suppose un déclenchement depuis une branche de confiance et un nouveau nom de branche ; si vous relancez l’exécution avec une branche existante, vous devez décider explicitement de la réutiliser ou de la remplacer. Ce workflow n’écrit pas les résultats dans un fork.

La pull request cible la branche depuis laquelle vous avez déclenché la tâche. Si GitHub indique que ses workflows attendent une approbation, une personne disposant d’un accès en écriture au dépôt doit choisir Approuver l’exécution des workflows ; consultez le comportement de GITHUB_TOKEN dans GitHub. Examinez le diff traduit, les vérifications et le résultat dans l’application avant de fusionner.

Des commits directs sur la branche à l’origine du déclenchement sont possibles avec une politique de branche adaptée, mais ils suppriment cette étape distincte de relecture du contenu et nécessitent un mécanisme de prévention des boucles.

Planifier les tâches et gérer les monorepos #

Une fois que la première exécution a donné un résultat utile, ajoutez des branches de confiance pour les déclenchements par push et des filtres sur les chemins des sources. Les commits de traduction générés ne doivent pas déclencher sans cesse une nouvelle tâche de traduction. Combinez des filtres de branche ou de chemin adaptés avec l’arrêt en l’absence de modifications dans l’étape de livraison.

Pour un monorepo, utilisez comme répertoire de travail de l’étape de traduction le package contenant .lingo/config.json. Mettez à jour les chemins des artefacts et des fichiers ajoutés à l’index pour y inclure ce package. Une matrice peut traiter des packages indépendants, mais deux entrées ne doivent pas mettre à jour la même configuration et le même Lockfile en parallèle. Les entrées d’une même exécution partagent le même identifiant d’exécution : attribuez donc à chacune un nom d’artefact et une branche de traduction distincts, par exemple en ajoutant le nom du package à translated-catalog et lingo/translations-${GITHUB_RUN_ID}.

Récupérer une exécution incomplète #

Partez de l’état signalé : corrigez les erreurs des cibles en échec, prenez les décisions nécessaires pour les cibles en attente de relecture et, en cas de conflit de récupération en local, choisissez entre la modification locale et le résultat téléchargé. Gardez les résultats réussis disponibles pour examen, tout en laissant les langues incomplètes non résolues. Un résultat partiel ne doit pas passer pour une version complète dans une langue.

Gardez les codes de sortie non nuls visibles. || true, une récupération forcée qui écrase les modifications ou le traitement forcé de toutes les cibles peuvent masquer la cause et remplacer un travail déjà accepté. Le guide des workflows CI explique comment préserver la révision et l’état de référence pendant la récupération.

Désactivez le workflow ou son déclencheur pour empêcher le lancement de nouvelles tâches du runner. Si une tâche a déjà soumis une traduction, examinez séparément cette exécution côté serveur lorsque vous annulez la tâche dans Actions. Supprimez les secrets inutilisés et l’accès en écriture au dépôt lorsque vous mettez le workflow hors service.