Intégration Lingo.dev avec Bitbucket

L'intégration Lingo.dev avec Bitbucket Pipelines est une intégration CI/CD open-source et sécurisée qui localise automatiquement les nouveaux contenus et empêche les traductions incomplètes d'atteindre la production. Elle crée des pull requests ou des commits directement sur votre branche, selon les exigences de flux de travail de votre équipe.

Elle implémente également une 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. Pull requests 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 par commits directs ou par pull requests ;
  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 Lingo.dev avec Bitbucket 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 du dépôt → Variables du dépôt de votre dépôt, 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 Bitbucket (pour le mode Pull Request)

Si vous prévoyez d'utiliser le mode pull request, créez un jeton d'accès :

  1. Allez dans Paramètres du dépôt → Jetons d'accès → Créer un jeton d'accès au dépôt
  2. Accordez ces autorisations :
    • Lecture et écriture des dépôts
    • Lecture et écriture des pull requests
  3. Ajoutez le jeton comme variable de dépôt :
    • Nom de variable : BB_TOKEN
    • Valeur de variable : Votre jeton d'accès Bitbucket

Étape 2. Créer le workflow

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

script:
  - pipe: lingodotdev/lingo.dev:main

Cette configuration utilise le pipe Lingo.dev et exécute automatiquement le moteur de traduction.

Permissions requises

Bitbucket Pipelines nécessite un accès aux variables du dépôt et aux opérations git :

Variables du dépôt :

  • LINGODOTDEV_API_KEY — Obligatoire pour les utilisateurs du moteur Lingo.dev
  • OPENAI_API_KEY ou ANTHROPIC_API_KEY — Obligatoire pour les utilisateurs d'API LLM brutes

Pour le mode Pull Request :

  • BB_TOKEN — Obligatoire pour créer et gérer les pull requests

Portées des jetons d'accès (lors de l'utilisation du mode pull request) :

  • Lecture et écriture des dépôts — Accès et modification du contenu du dépôt
  • Lecture et écriture des pull requests — Création et gestion des pull requests

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 Lingo.dev pour Bitbucket 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 dans votre branche :

script:
  - pipe: lingodotdev/lingo.dev:main

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 fusion
  • Les projets où les mises à jour de traduction ne nécessitent pas de révision séparée

Mode Pull Request

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

script:
  - pipe: lingodotdev/lingo.dev:main
    variables:
      LINGODOTDEV_PULL_REQUEST: "true"

Configuration requise pour le mode Pull Request

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

Exigences du jeton d'accès : Votre BB_TOKEN doit inclure des permissions de lecture et d'écriture pour les dépôts et les pull requests.

Remarque : La variable BB_TOKEN est obligatoire lors de l'utilisation du mode pull request.

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 Lingo.dev Bitbucket 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

image:
  name: atlassian/default-image:2

pipelines:
  branches:
    feat/*:
      - step:
          name: Run i18n
          script:
            - pipe: lingodotdev/lingo.dev:main

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 : Pull Requests pour les mises à jour (mode Pull Request)

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

image:
  name: atlassian/default-image:2

pipelines:
  branches:
    feat/*:
      - step:
          name: Run i18n
          script:
            - pipe: lingodotdev/lingo.dev:main
              variables:
                LINGODOTDEV_API_KEY: "${MY_LINGODOTDEV_API_KEY}" # ou OPENAI_API_KEY/ANTHROPIC_API_KEY
                BB_TOKEN: "${MY_ACCESS_TOKEN}"
                LINGODOTDEV_PULL_REQUEST: "true"
                LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
                LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations"
                LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
                LINGODOTDEV_PROCESS_OWN_COMMITS: "true"

Flux : Modifications de contenu poussées vers la branche → L'intégration crée une pull request 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 :

image:
  name: atlassian/default-image:2

pipelines:
  branches:
    feat/*:
      - step:
          name: Run i18n
          script:
            - pipe: lingodotdev/lingo.dev:main
              variables:
                LINGODOTDEV_API_KEY: "${MY_LINGODOTDEV_API_KEY}"
                BB_TOKEN: "${MY_ACCESS_TOKEN}"
                LINGODOTDEV_PULL_REQUEST: "true"
                LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
                LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations"
                LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
                LINGODOTDEV_PROCESS_OWN_COMMITS: "true"

Exemple avec l'API LLM brute :

image:
  name: atlassian/default-image:2

pipelines:
  branches:
    feat/*:
      - step:
          name: Run i18n
          script:
            - pipe: lingodotdev/lingo.dev:main
              variables:
                OPENAI_API_KEY: "${MY_OPENAI_API_KEY}" # ou ANTHROPIC_API_KEY
                BB_TOKEN: "${MY_ACCESS_TOKEN}"
                LINGODOTDEV_PULL_REQUEST: "true"
                LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
                LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations"
                LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
                LINGODOTDEV_PROCESS_OWN_COMMITS: "true"

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 pull request au lieu d'un commit direct (par défaut : false)
  • LINGODOTDEV_PULL_REQUEST_TITLE — Titre personnalisé de la pull request (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)
  • BB_TOKEN — Jeton d'accès Bitbucket (requis pour le mode pull request)