Exemple de configuration CI pour GitLab

Traduisez vos fichiers dans un pipeline GitLab de confiance, livrez-les via une demande de fusion et faites échouer les demandes de fusion dont les traductions ne sont plus à jour.

Un runner GitLab peut traduire les fichiers du dépôt avec la CLI Lingo.dev et conserver les résultats sous forme d’artefacts de job. La traduction suit ainsi le même checkout, les mêmes vérifications et le même processus de publication que le reste de votre application. GitLab gère l’exécution du pipeline et la livraison dans le dépôt ; Lingo.dev traite les fichiers sources sélectionnés à l’aide d’un moteur de localisation.

Il s’agit d’un exemple de configuration CI, et non d’une connexion native à un compte GitLab. Commencez par lancer manuellement un pipeline sur la branche par défaut. Après avoir vérifié le résultat, ajoutez des déclencheurs récurrents et la livraison par demande de fusion.

Configurer la source et les identifiants #

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. Exécutez la CLI depuis le répertoire qui contient cette configuration.

Créez les fichiers cibles manquants avec lingo push --backfill-missing --wait. Pour les modifications ultérieures de la source, utilisez la commande lingo push --wait habituelle. Modifier les instructions du moteur de localisation ne réécrit pas automatiquement les fichiers acceptés ; leur régénération volontaire constitue une tâche distincte.

Dans les paramètres des variables CI/CD du projet, enregistrez LINGO_API_KEY comme variable masquée. La CLI ne reconnaît que ce nom ; elle ignore toute variable LINGODOTDEV_API_KEY issue de l'ancienne CLI. Renommez-la donc. Réservez son utilisation aux branches ou environnements de confiance autorisés à soumettre des tâches de traduction. Une variable protégée peut être indisponible sur une branche ou une demande de fusion non protégée ; utilisez une branche autorisée plutôt que d'exposer cette variable à du code non fiable.

La clé API autorise la traduction. Un identifiant GitLab donnant accès au dépôt en écriture n’est nécessaire que si vous ajoutez la livraison par commit.

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 CI.

Exécuter un pipeline avec livraison initiale sous forme d’artefacts #

Cet exemple .gitlab-ci.yml suppose que locales/en.json est la source configurée et que locales/es.json, un fichier espagnol existant, est sa seule 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 toute cible omise de l'artefact ou du commit reste obsolète. L'exemple utilise un pipeline lancé manuellement sur la branche par défaut :

yaml
stages:
  - translate

translate_catalog:
  stage: translate
  image: node:22
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  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:
    paths:
      - locales/es.json
      - .lingo/lock.json

Avec --wait, la tâche attend 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. Les étapes suivantes ne trouvent donc aucun nouveau fichier à inspecter ou à committer.

Vérifiez que votre runner peut accéder au registre et fournissez les outils nécessaires aux étapes suivantes. Par exemple, si vous choisissez une autre image minimale, vous devrez peut-être y installer Git pour pouvoir examiner un diff ou effectuer un commit.

Vérifiez les identifiants de l’organisation et du moteur dans le fichier .lingo/config.json committé. Effectuez une modification de la source, puis lancez le pipeline. Dans le journal, vérifiez l’état d’exécution indiqué et l’entrée cible modifiée. Téléchargez l’artefact, comparez la traduction à cette révision de la source et chargez-la dans votre application. Les vérifications de présence des fichiers et de validité JSON ne suffisent pas, à elles seules, à confirmer que le contenu est à jour ou que son sens est correct.

--wait télécharge le résultat une fois terminé, mais si la relecture humaine est configurée, le travail peut rester en attente d’une intervention. Avant d’utiliser une attente de relecture ou un job de récupération distinct, ajoutez la procédure de conservation de l’état d’exécution en CI. Après la soumission, exportez le pointeur spécifique et le chemin absolu d’origine de la racine du projet. Incluez .lingo-ci/run.json, .lingo-ci/project-root.txt, .lingo/config.json, locales/en.json, la cible et le Lockfile dans des artefacts de job à accès restreint. Définissez when: always dans la configuration artifacts et prévoyez une durée de conservation suffisante pour la relecture. Veillez à ce que l’export s’exécute aussi en cas d’échec d’une validation ultérieure, sans masquer l’échec initial.

Terminez la relecture, puis restaurez la révision et l’état des fichiers enregistrés sur le runner de récupération, en utilisant le même chemin absolu pour la racine du projet. Restaurez uniquement ce pointeur, authentifiez-vous séparément et utilisez lingo pull --dry-run avant la collecte. Si le runner ne peut pas recréer le chemin d’origine, utilisez plutôt un runner persistant autorisé pour les deux jobs. N’archivez jamais l’intégralité de ~/.lingo. Ni une soumission réussie ni un ancien fichier cible ne suffisent à fournir de nouveaux fichiers à publier.

Committer les traductions dans une demande de fusion #

Ce job traduit les modifications de la source dans une demande de fusion et committe les résultats sur la même branche. Il suppose que le remplissage rétroactif initial a été committé et que la relecture humaine du moteur est désactivée, pour permettre à la traduction de se terminer en un seul job.

Sur GitLab 18.4 ou une version ultérieure, activez Paramètres → CI/CD → Autorisations des jetons de job → Autoriser les requêtes Git push vers le dépôt. Le job utilise le jeton intégré de GitLab ; la personne qui le lance doit être autorisée à pousser vers la branche source. Consultez la configuration des jetons de job de GitLab.

Conservez LINGO_API_KEY masqué et protégé. Utilisez des branches source et cible de confiance dans le même projet, protégez-les toutes les deux et activez Autoriser les pipelines de demandes de fusion à accéder aux variables et runners protégés dans les paramètres CI/CD du projet. La personne qui lance le pipeline doit aussi être autorisée à pousser ou à fusionner vers la branche cible. Ce sont les exigences de GitLab concernant les variables protégées.

Utilisez les mêmes chemins source et cible que dans le premier exemple. Ajoutez ce job à l’étape translate :

yaml
translate_merge_request:
  stage: translate
  image: node:22
  resource_group: lingo-mr-$CI_MERGE_REQUEST_IID
  rules:
    - if: >-
        $CI_PIPELINE_SOURCE == "merge_request_event" &&
        $CI_MERGE_REQUEST_EVENT_TYPE == "detached" &&
        $CI_MERGE_REQUEST_SOURCE_PROJECT_ID == $CI_MERGE_REQUEST_TARGET_PROJECT_ID
  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 "Update translations"
    - git push "$CI_REPOSITORY_URL" "HEAD:refs/heads/$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"

resource_group exécute un seul job de traduction à la fois pour chaque MR. Le job ne committe que la cible espagnole et le Lockfile de traduction. Si la branche change pendant la traduction, Git refuse le push ; lancez alors un pipeline pour la branche mise à jour.

CI_REPOSITORY_URL fournit les identifiants du jeton de job. Les push effectués avec ce jeton ne déclenchent pas d’autre pipeline ; ajoutez donc les vérifications des ressources de votre application avant l’étape de commit. Relisez le diff de traduction dans la MR et exécutez les vérifications restantes avant de fusionner.

Comme ce push ne lance aucun pipeline, le dernier commit de la demande de fusion n'en a pas. Si le projet impose l'option Les pipelines doivent réussir, GitLab peut bloquer la fusion. Sélectionnez alors Exécuter le pipeline dans l'onglet Pipelines de la demande de fusion. La tâche ne trouve rien à pousser et se termine sans commit ; ce pipeline attribue alors un statut au dernier commit.

Ouvrir une demande de fusion de traductions depuis la branche par défaut #

Cette tâche traduit chaque modification qui arrive sur la branche par défaut et ouvre une demande de fusion avec le résultat. Les options de push de GitLab créent la demande de fusion dans le même git push, sans appel API ni outil supplémentaire. Cette tâche repose sur les mêmes hypothèses que la précédente : le remplissage rétroactif initial a été committé et la relecture humaine est désactivée.

Créez un jeton d'accès au projet avec le rôle Développeur et la portée write_repository. Enregistrez-le comme variable CI/CD masquée et protégée sous le nom GITLAB_PUSH_TOKEN. Sur GitLab.com, les jetons d'accès au projet nécessitent une offre payante. CI_JOB_TOKEN n'est pas utilisé ici, car GitLab ne lance aucun pipeline pour un push effectué avec ce jeton. L'URL de push utilise CI_SERVER_FQDN, qui conserve le port d'une instance autogérée lorsque celui-ci n'est pas standard. CI_SERVER_FQDN nécessite GitLab 16.10 ou une version ultérieure. Sur une instance autogérée plus ancienne, utilisez plutôt ${CI_SERVER_HOST}:${CI_SERVER_PORT}.

Ajoutez cette tâche à l'étape translate :

yaml
translate_default_branch:
  stage: translate
  image: node:22
  resource_group: lingo-translations
  rules:
    - if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  script:
    - git fetch --quiet "$CI_REPOSITORY_URL" "$CI_DEFAULT_BRANCH"
    - if [ "$(git rev-parse FETCH_HEAD)" != "$CI_COMMIT_SHA" ]; then exit 0; fi
    # 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 --force
      -o ci.skip
      -o merge_request.create
      -o merge_request.target="$CI_DEFAULT_BRANCH"
      -o merge_request.title="Update translations"
      "https://oauth2:${GITLAB_PUSH_TOKEN}@${CI_SERVER_FQDN}/${CI_PROJECT_PATH}.git"
      "HEAD:refs/heads/lingo/translations"

lingo push --wait se termine avec un code de sortie non nul si une cible échoue : la tâche s'arrête donc avant le commit. Si rien n'a changé, elle affiche "Rien à pousser", le diff des modifications indexées est vide et la tâche se termine sans commit.

Les deux premières lignes arrêtent la tâche si la branche par défaut a avancé au-delà du commit sur lequel elle s'exécute. resource_group exécute une seule tâche à la fois, mais avec le mode de traitement unordered par défaut de GitLab, les tâches en attente démarrent sans ordre défini. Sans cette vérification, une tâche plus ancienne pourrait s'exécuter en dernier et écraser les traductions récentes par des traductions plus anciennes lors d'un push forcé. La tâche associée au dernier commit traduit celui-ci, et rien n'est soumis pour un commit déjà dépassé.

La tâche ne s'exécute pas en boucle. Elle ne se lance que lors des push vers la branche par défaut et n'écrit que dans lingo/translations. La documentation de GitLab indique que -o ci.skip n'affecte que les pipelines de branche, pas ceux des demandes de fusion, et qu'un pipeline de demande de fusion s'exécute à la création de la demande ou lorsque sa branche source reçoit un nouveau commit. Le contrôle ci-dessous devrait donc s'exécuter sur la demande de fusion de traductions ; vérifiez que c'est bien le cas lors de la première exécution. La fusion de cette demande lance la tâche une nouvelle fois, mais celle-ci ne trouve alors rien à pousser.

Chaque exécution reconstruit lingo/translations à partir du commit de la branche par défaut sur lequel elle s'est exécutée, puis effectue un push forcé. Une demande de fusion ouverte affiche ainsi le dernier diff de traduction. L'exécution suivante remplace les modifications manuelles apportées à cette branche ; faites-les après la fusion. Tant que la demande de fusion n'est pas fusionnée, la branche par défaut conserve le précédent .lingo/lock.json : l'exécution suivante soumet donc à nouveau les mêmes modifications des sources. Si des commits ultérieurs annulent toutes les modifications des sources traduites par la demande de fusion, l'exécution suivante ne trouve rien à pousser et laisse la demande ouverte avec des traductions obsolètes ; fermez-la au lieu de la fusionner.

Faire échouer les demandes de fusion dont les traductions ne sont plus à jour #

lingo check compare chaque source configurée avec .lingo/lock.json et exige la présence de tous les fichiers cibles. La commande se termine avec 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 CI/CD et n'écrit rien : elle peut donc aussi s'exécuter sur les demandes de fusion provenant de forks. Hormis la télémétrie de la CLI, que DO_NOT_TRACK=1 désactive, elle ne fait aucun appel réseau ; les exemples npx téléchargent toutefois la CLI depuis npm avant 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 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 des sources : une source modifiée ou jamais poussée ne fait donc pas échouer la vérification, qui signale cette limite sur stderr. Committez le Lockfile écrit par lingo push.

Ajoutez check à la liste stages, puis ajoutez la tâche adaptée à votre configuration. Lorsque les développeurs exécutent lingo push --wait et committent le résultat avec leur modification de la source, vérifiez chaque demande de fusion :

yaml
check_translations:
  stage: check
  image: node:22
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  script:
    # lingo check needs CLI 1.20.0 or newer.
    - npx -y @lingo.dev/cli@1.21.0 check

Avec la tâche de la branche par défaut, vérifiez uniquement la demande de fusion de traductions qu'elle crée, car les demandes de fusion de fonctionnalités modifient les sources avant la traduction :

yaml
check_translations:
  stage: check
  image: node:22
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME == "lingo/translations"'
  script:
    # lingo check needs CLI 1.20.0 or newer.
    - npx -y @lingo.dev/cli@1.21.0 check

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

Où s'exécute la traductionContrôle sur chaque demande de fusion
Les développeurs exécutent lingo push --wait et committent le résultat avant d'ouvrir la demande de fusionOui. Il fait échouer toute demande de fusion dont la source a changé sans être traduite.
La tâche de la demande de fusion effectue un commit sur la branche sourceNon. La vérification inspecterait le commit avant la traduction, et le push de la tâche ne lance aucun nouveau pipeline.
La tâche de la branche par défaut ouvre une demande de fusion de traductionsUniquement sur lingo/translations, avec la deuxième tâche ci-dessus. Par conception, les demandes de fusion de fonctionnalités modifient les sources avant la traduction.

Les empreintes des sources sont calculées à l'octet près. Assurez-vous que le checkout qui a exécuté lingo push et le checkout CI utilisent les mêmes fins de ligne, par exemple avec * text=auto eol=lf dans .gitattributes.

Rendre les tâches récurrentes prévisibles #

Filtrez les jobs automatiques pour ne cibler que les branches de confiance et les chemins sources prévus. Si vous utilisez des déclencheurs de demandes de fusion, limitez aussi le projet source et la branche cible. Empêchez les commits générés de soumettre des traductions en boucle : utilisez une règle de branche ou une politique adaptée pour ignorer la CI, et quittez lorsque le diff est vide.

Pour un monorepo, placez-vous dans le paquet qui contient la configuration souhaitée et conservez ses résultats et son état avec des chemins relatifs à ce paquet. Les paquets indépendants peuvent utiliser des moteurs de localisation et des langues différents ; gardez leurs fichiers Lockfile séparés. La même approche avec un runner fonctionne sur GitLab autogéré lorsque l’accès réseau, les outils du runner, les variables et les règles du dépôt le permettent.

La traduction incrémentale habituelle peut conserver une clé cible modifiée manuellement tant que sa source reste inchangée. Une modification de la source peut entraîner la régénération de cette clé. Le remplissage rétroactif des fichiers manquants et la régénération forcée ont des périmètres différents. Sans motifs de fichiers, --force couvre toutes les langues sources et cibles configurées et peut remplacer des traductions acceptées. Utilisez des motifs explicites et examinez une estimation avant de forcer le travail. Consultez Pousser lorsque vous modifiez la commande de soumission.

Rétablir le pipeline et le retirer du service #

Appuyez-vous sur l’erreur pour déterminer la prochaine action : réparer l’installation du paquet, fournir une variable autorisée, terminer la relecture, résoudre un conflit de fusion ou réessayer le travail de traduction ayant échoué sur la cible après en avoir corrigé la cause. Conservez les artefacts réussis, mais indiquez clairement qu’une publication partiellement terminée reste incomplète.

Désactivez le déclencheur pour empêcher le lancement de nouveaux pipelines. Si vous annulez le runner, examinez séparément toute traduction déjà soumise. Supprimez les identifiants API et de dépôt obsolètes lorsque vous retirez cette configuration du service.