GitLab CI/CD

Exécutez Lingo.dev dans GitLab CI pour que chaque merge request qui ajoute ou modifie des chaînes source revienne avec les traductions déjà remplies. Le pipeline exécute lingo push, le moteur de localisation ne traduit que les nouvelles clés ou celles qui ont changé, puis le résultat est commité directement sur la branche de la MR — les traductions apparaissent dans le diff de la MR et sont relues avant qu’une personne ne fusionne. Rien n’arrive sur votre branche par défaut sans avoir été vu.

Prérequis#

• Une organisation Lingo.dev et un moteur, ainsi qu’une clé d’API de service (Dashboard → API Keys → create, type service).

• Un projet configuré pour Lingo.dev. Générez-le une première fois avec :

  bashCopy

  npx @lingo.dev/cli@latest init   # scaffolds .lingo/config.json
  npx @lingo.dev/cli@latest link   # connects the project to your org + engine

  .lingo/config.json définit les langues source et cible ainsi que les globs source :

  jsonCopy

  {
    "sourceLocale": "en",
    "targetLocales": ["es", "fr", "de", "zh"],
    "files": [{ "pattern": "locales/en.json" }],
    "orgId": "org_...",
    "engineId": "eng_..."
  }

• Une base de référence déjà commitée. La toute première fois, traduisez tout et commitez le résultat afin que la CI dispose d’un lockfile avec lequel comparer :

  bashCopy

  npx @lingo.dev/cli@latest push --backfill-missing --wait
  git add locales .lingo && git commit -m "chore(i18n): baseline translations"

Jetons d’accès#

Ajoutez deux variables CI/CD masquées dans Settings → CI/CD → Variables :

• LINGO_API_KEY — votre clé de service Lingo.dev (lingo_sk_...). La CLI l’utilise automatiquement pour s’authentifier.
• GITLAB_PUSH_TOKEN — un Project Access Token avec le scope write_repository (rôle Developer). Cela permet à la CI de commiter les traductions sur la branche de la MR.

Pipeline#

Commitez ce .gitlab-ci.yml. Il s’exécute sur les merge requests ciblant la branche par défaut et renvoie les traductions sur la branche source de la MR :

stages:
  - localize

localize:
  stage: localize
  image: node:22-alpine
  rules:
    # Only on merge requests that target the default branch.
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH'
  before_script:
    - apk add --no-cache git
  script:
    # Pin the CLI version — never @latest; bump deliberately after testing.
    # --wait blocks until the engine finishes and writes files: since 1.6.0
    # `push` is async by default (it submits the run and exits), so CI must
    # wait to have something to commit.
    - npx -y @lingo.dev/cli@1.6.0 push --wait
    - |
      if [ -z "$(git status --porcelain)" ]; then
        echo "Translations already up to date — nothing to commit."
        exit 0
      fi
      git config user.name "lingo-bot"
      git config user.email "bot@lingo.dev"
      git add locales .lingo/lock.json
      # [skip ci] keeps the bot's own commit from re-triggering this pipeline.
      git commit -m "chore(i18n): sync translations [skip ci]"
      git push "https://oauth2:${GITLAB_PUSH_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git" "HEAD:${CI_MERGE_REQUEST_SOURCE_BRANCH_NAME}"

Essayez#

git checkout -b feat/new-strings
# add or change a key in locales/en.json
git commit -am "feat: add strings" && git push -u origin feat/new-strings
# open an MR feat/new-strings -> main (UI, or: glab mr create --fill --target-branch main)

Le pipeline de MR exécute lingo push --wait, commite locales/{...}.json ainsi que le .lingo/lock.json mis à jour sur la branche de la MR, et les traductions apparaissent dans le diff. Un relecteur ajuste les valeurs si besoin, puis fusionne.

Comment les modifications humaines sont conservées#

lingo push préserve les modifications manuelles clé par clé :

• Modifiez une chaîne cible (sans changer sa source anglaise) → cette chaîne est conservée ; toutes les autres clés continuent d’être traduites.
• La source anglaise d’une clé modifiée change → une nouvelle traduction est générée pour cette clé (le sens a changé).
• Une nouvelle clé source est ajoutée → elle est traduite et ajoutée, même dans des fichiers qui contiennent des modifications manuelles.

Ainsi, la correction apportée par un relecteur dans la MR est conservée à chaque exécution suivante du pipeline, tandis que les clés nouvelles et modifiées continuent d’être ajoutées automatiquement.

Modes de push#

• lingo push — incrémentiel ; le mode par défaut en CI. Ne traduit que les clés nouvelles ou modifiées, et préserve tout le reste. Ajoutez --wait dans la CI pour qu’il attende que les sorties soient écrites (1.6.0+ est asynchrone par défaut).
• lingo push --backfill-missing — premier push / initialisation d’une nouvelle langue ; remplit les fichiers cibles qui n’existent pas encore. Pas adapté aux changements continus.
• lingo push --force --yes — retraduit tout depuis zéro (écrase les modifications manuelles). Rare.

Personnalisation#

• Commit automatique sur la branche par défaut au lieu des MR : déclenchez sur $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH et poussez vers $CI_DEFAULT_BRANCH. C’est plus simple, mais la sortie de l’IA arrive sur la branche par défaut sans relecture.
• Épingler des chaînes spécifiques : utilisez preservedKeys / lockedKeys dans .lingo/config.json pour garder certaines clés fixes même lorsque leur source change.
• GitLab auto-hébergé : fonctionne sans modification. Sur gitlab.com, les nouveaux comptes doivent passer une vérification d’identité avant que les runners partagés n’exécutent les jobs CI.

Étapes suivantes#