Intégration GitLab de Lingo.dev

L'intégration CI/CD GitLab de Lingo.dev est une intégration CI/CD open-source sécurisée qui localise automatiquement le nouveau contenu et empêche les traductions incomplètes d'atteindre la production. Elle crée des demandes de fusion ou des commits directement sur votre branche, selon les exigences de flux de travail de votre équipe.

Elle implémente également la résolution automatique des conflits par rebasing, de sorte que vos traductions restent synchronisées avec votre code sans intervention manuelle.

L'intégration prend en charge plusieurs scénarios de flux de travail :

1. Commits directs sur les branches lorsque des modifications de contenu sont poussées
2. Demandes de fusion ciblant des branches pour les mises à jour de traduction

À la fin de ce guide, vous aurez :

1. Configuré la localisation automatisée déclenchée par les push de code ;
2. Configuré l'authentification sécurisée à l'aide de variables de dépôt ;
3. Choisi entre les flux de travail de commits directs ou de demandes de fusion ;
4. Compris comment la localisation continue s'intègre dans votre processus existant.

Commençons !

Prérequis

Configuration du dépôt

Votre dépôt doit avoir Lingo.dev CLI configuré avec un fichier i18n.json valide. Si vous ne l'avez pas encore configuré, complétez d'abord le démarrage rapide CLI.

Étape 1. Configuration de l'authentification

L'intégration GitLab de Lingo.dev nécessite un accès à votre moteur de traduction et à votre dépôt. L'authentification s'effectue via des variables de dépôt qui maintiennent vos identifiants sécurisés.

Ajoutez votre clé API

Naviguez vers Paramètres de votre dépôt → CI/CD → Variables, puis ajoutez les identifiants de votre moteur de traduction :

Pour les utilisateurs d'API LLM brute :

• Nom de variable : OPENAI_API_KEY ou ANTHROPIC_API_KEY
• Valeur de variable : Votre clé API du fournisseur respectif

Pour les utilisateurs du moteur Lingo.dev :

• Nom de variable : LINGODOTDEV_API_KEY
• Valeur de variable : Votre clé API de projet depuis lingo.dev/app

Ajoutez un jeton d'accès GitLab

Créez un jeton d'accès personnalisé pour les opérations de dépôt :

1. Allez dans Paramètres → Jetons d'accès → Ajouter un nouveau jeton
2. Accordez ces portées :
   • api
   • read_repository
   • write_repository
3. Ajoutez le jeton comme variable de dépôt :
   • Nom de variable : GL_TOKEN
   • Valeur de variable : Votre jeton d'accès GitLab

Important : Le jeton de job CI par défaut n'est pas suffisant. Vous devez créer un jeton d'accès personnalisé car le jeton par défaut ne dispose pas des permissions nécessaires pour les opérations git.

Remarque : Pour les branches protégées, assurez-vous que vos variables sont également marquées comme protégées. Les variables non protégées ne seront pas accessibles dans les pipelines de branches protégées.

Étape 2. Créer le workflow

Créez ou mettez à jour votre fichier .gitlab-ci.yml avec cette configuration de base :

lingodotdev:
  image: lingodotdev/ci-action:latest
  script:
    - echo "Done"

Cette configuration utilise la dernière image Docker et exécute automatiquement le moteur de traduction.

Permissions requises

GitLab CI/CD nécessite un accès aux variables du dépôt et aux opérations git :

Variables du dépôt :

• LINGODOTDEV_API_KEY — Requis pour les utilisateurs du moteur Lingo.dev
• OPENAI_API_KEY ou ANTHROPIC_API_KEY — Requis pour les utilisateurs d'API LLM brutes
• GL_TOKEN — Requis pour les opérations de push git et la création de demandes de fusion

Portées du jeton d'accès :

• api — Créer et gérer les demandes de fusion
• read_repository — Accéder au contenu du dépôt
• write_repository — Pousser des commits et créer des branches

Ces permissions permettent à l'intégration de lire votre contenu, de générer des traductions et de mettre à jour votre dépôt avec le contenu localisé.

Étape 3. Choisir votre mode de workflow

L'intégration GitLab de Lingo.dev prend en charge deux modes opérationnels selon les exigences de revue de code de votre équipe.

Mode commit direct (par défaut)

L'intégration commit les traductions directement sur votre branche :

lingodotdev:
  image: lingodotdev/ci-action:latest
  script:
    - echo "Done"

Ce mode convient particulièrement pour :

• Les développeurs individuels ou les petites équipes
• Les branches de fonctionnalités qui seront révisées avant la fusion
• Les projets où les mises à jour de traduction ne nécessitent pas de révision séparée

Mode demande de fusion

L'intégration crée des demandes de fusion pour les mises à jour de traduction :

lingodotdev:
  image: lingodotdev/ci-action:latest
  variables:
    LINGODOTDEV_PULL_REQUEST: "true"
  script:
    - echo "Done"

Configuration requise pour le mode demande de fusion

Variables du dépôt : Les variables LINGODOTDEV_API_KEY et GL_TOKEN doivent être configurées comme variables du dépôt.

Exigences du jeton d'accès : Votre GL_TOKEN doit inclure la portée api pour créer et gérer les demandes de fusion.

Ce mode convient particulièrement pour :

• Les équipes avec des exigences strictes de revue de code
• Les projets où les modifications de traduction nécessitent une approbation séparée
• Les workflows qui nécessitent une révision explicite de toutes les modifications

Étape 4. Scénarios de flux de travail

L'intégration GitLab de Lingo.dev s'adapte à différents flux de travail de développement. Comprendre ces scénarios vous aide à choisir la configuration appropriée pour votre équipe.

Scénario 1 : Mises à jour de branches fonctionnelles (commits directs)

Déclencheur : Push vers les branches fonctionnelles Action : Commit les mises à jour de traduction directement sur la branche fonctionnelle

lingodotdev:
  image: lingodotdev/ci-action:latest
  script:
    - echo "Done"
  rules:
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH = /^feat/

Flux : Modifications de contenu poussées vers la branche fonctionnelle → L'intégration commit les traductions sur la même branche

Cela maintient les mises à jour de traduction dans la branche fonctionnelle, garantissant que les traductions sont révisées en même temps que les modifications originales.

Scénario 2 : Demandes de fusion pour les mises à jour (mode demande de fusion)

Déclencheur : Push vers n'importe quelle branche configurée Action : Crée une demande de fusion avec les mises à jour de traduction

lingodotdev:
  image: lingodotdev/ci-action:latest
  variables:
    LINGODOTDEV_API_KEY: $MY_LINGODOTDEV_API_KEY # ou OPENAI_API_KEY/ANTHROPIC_API_KEY
    LINGODOTDEV_PULL_REQUEST: "true"
    LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
  script:
    - echo "Done"

Flux : Modifications de contenu poussées vers la branche → L'intégration crée une demande de fusion avec les traductions

Cela maintient des révisions séparées pour les mises à jour de traduction.

Configuration avancée

Personnalisez le comportement de l'intégration en utilisant des variables supplémentaires :

Exemple avec le moteur Lingo.dev :

lingodotdev:
  image: lingodotdev/ci-action:latest
  variables:
    LINGODOTDEV_API_KEY: $MY_LINGODOTDEV_API_KEY
    GL_TOKEN: $MY_GL_TOKEN
    LINGODOTDEV_PULL_REQUEST: "true"
    LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
    LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations via @lingodotdev"
    LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
    LINGODOTDEV_PROCESS_OWN_COMMITS: "true"
  script:
    - echo "Done"
  rules:
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH = /^feat/

Exemple avec l'API LLM brute :

lingodotdev:
  image: lingodotdev/ci-action:latest
  variables:
    OPENAI_API_KEY: $MY_OPENAI_API_KEY # ou ANTHROPIC_API_KEY
    GL_TOKEN: $MY_GL_TOKEN
    LINGODOTDEV_PULL_REQUEST: "true"
    LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
    LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations via @lingodotdev"
    LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
    LINGODOTDEV_PROCESS_OWN_COMMITS: "true"
  script:
    - echo "Done"
  rules:
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH = /^feat/

Options de configuration :

• LINGODOTDEV_API_KEY — Votre clé API du moteur Lingo.dev, si vous utilisez le moteur Lingo.dev
• OPENAI_API_KEY — Votre clé API OpenAI, si vous utilisez l'API LLM brute
• ANTHROPIC_API_KEY — Votre clé API Anthropic, si vous utilisez l'API LLM brute
• LINGODOTDEV_PULL_REQUEST — Créer une demande de fusion au lieu d'un commit direct (par défaut : false)
• LINGODOTDEV_PULL_REQUEST_TITLE — Titre personnalisé de la demande de fusion (par défaut : feat: update translations via @lingodotdev)
• LINGODOTDEV_COMMIT_MESSAGE — Message de commit personnalisé (par défaut : feat: update translations via @lingodotdev)
• LINGODOTDEV_WORKING_DIRECTORY — Exécuter l'intégration dans un sous-répertoire (par défaut : .)
• LINGODOTDEV_PROCESS_OWN_COMMITS — Traiter les commits effectués par cette intégration (par défaut : false)

Dépannage

Erreurs courantes et leurs solutions :