Intégration GitHub de Lingo.dev

L'action GitHub Lingo.dev est une intégration CI/CD sécurisée et open-source 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, de sorte que vos traductions restent synchronisées avec votre code sans intervention manuelle.

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

Commits directs vers la branche principale lorsque les modifications de contenu sont fusionnées
Commits directs vers les branches de pull request lorsque les PR sont ouvertes ou mises à jour
Pull requests ciblant la branche principale pour les mises à jour de traduction
Pull requests ciblant les branches de pull request existantes pour les mises à jour de traduction

À la fin de ce guide, vous aurez :

Configuré une localisation automatisée déclenchée par les push de code ;
Configuré une authentification sécurisée à l'aide des secrets du dépôt ;
Choisi entre des commits directs ou des flux de travail par pull request ;
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

Les actions GitHub Lingo.dev ont besoin d'accéder à votre moteur de traduction et à votre dépôt. L'authentification s'effectue via des secrets de dépôt qui maintiennent vos identifiants sécurisés.

Ajoutez votre clé API

Naviguez vers les Paramètres de votre dépôt → Secrets et variables → Actions, puis ajoutez les identifiants de votre moteur de traduction :

Pour les utilisateurs d'API LLM brute :

Nom du secret : OPENAI_API_KEY ou ANTHROPIC_API_KEY
Valeur du secret : Votre clé API du fournisseur respectif

Pour les utilisateurs du moteur Lingo.dev :

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

Étape 2. Créer le workflow

Créez .github/workflows/i18n.yml dans votre dépôt avec cette configuration de base :

name: Lingo.dev i18n

on:
  workflow_dispatch:
  push:
    branches:
      - main
      - feat/*

permissions:
  contents: write
  pull-requests: write

jobs:
  i18n:
    name: Run i18n
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Alternativement, vous pouvez ajouter l'action GitHub Lingo.dev comme étape à votre workflow existant :

- name: Lingo.dev
  uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Permissions requises

Votre workflow nécessite des permissions spécifiques pour fonctionner correctement. GitHub Actions exige des déclarations explicites de permissions dans le fichier de workflow :

permissions:
  contents: write # Requis : Créer des commits avec des mises à jour de traduction
  pull-requests: write # Optionnel : Nécessaire uniquement si vous utilisez le mode pull request

La permission contents: write permet à l'action de :

Créer des commits avec des mises à jour de traduction
Pousser des modifications directement dans votre dépôt
Accéder et modifier des fichiers dans votre dépôt

Ces permissions sont accordées au jeton GitHub éphémère du workflow (${{ github.token }}), qui est automatiquement créé par GitHub pour chaque exécution de workflow et possède exactement les permissions que vous spécifiez dans le fichier de workflow.

Cette configuration :

Se déclenche lors des push vers les branches main et feature
Accorde les permissions nécessaires pour les commits et les pull requests
Utilise la dernière version de l'action pour les mises à jour automatiques
Accède de manière sécurisée à votre clé API via les secrets du dépôt

Bonus :

Chez Lingo.dev, nous aimons ajouter un déclencheur workflow_dispatch à chaque workflow, afin de pouvoir l'exécuter manuellement depuis l'interface GitHub Actions. C'est totalement optionnel, mais nous l'avons trouvé très utile.

Étape 3. Choisissez votre mode de workflow

Lingo.dev GitHub Actions prend en charge deux modes opérationnels selon les exigences de revue de code de votre équipe.

Mode commit direct (par défaut)

L'action commit les traductions directement sur votre branche :

- uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Ce mode fonctionne mieux 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 pull request

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

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true
    pull-request-title: "feat: update translations"

Permissions requises pour le mode pull request

Le mode pull request nécessite des permissions supplémentaires et des paramètres de dépôt :

permissions:
  contents: write # Requis : accès au contenu du dépôt et création de commits
  pull-requests: write # Requis : création et mise à jour des pull requests

Configuration du token GitHub : La variable d'environnement GH_TOKEN doit être définie sur ${{ github.token }}, qui est un token éphémère généré automatiquement par GitHub pour chaque exécution de workflow. Ce token possède exactement les permissions spécifiées dans la section permissions de votre fichier de workflow.

Paramètres du dépôt : Vous devez autoriser GitHub Actions à créer des pull requests dans les paramètres de votre dépôt :

Allez dans Paramètres → Actions → Général
Faites défiler jusqu'au bas de la page
Sous "Permissions de workflow", assurez-vous que "Autoriser GitHub Actions à créer et approuver des pull requests" est activé

Si vous ne voyez pas cette option dans les paramètres de votre dépôt, vérifiez les paramètres de votre organisation :

Allez dans Paramètres de votre organisation → Actions → Général
Recherchez le même paramètre "Autoriser GitHub Actions à créer et approuver des pull requests"

Ce mode fonctionne mieux 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 revue explicite de toutes les modifications

Étape 4. Scénarios de flux de travail

L'action GitHub Lingo.dev s'adapte automatiquement à 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 la branche principale (commits directs)

Déclencheur : Push vers la branche principale (par exemple, lors de la fusion des pull requests) Action : Commit les mises à jour de traduction directement sur la branche principale

on:
  push:
    branches: [main]

# L'action commit directement sur la branche principale

- uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Flux : Modifications de contenu poussées vers main → L'action commit les traductions vers main

Ce scénario garantit que votre branche principale dispose toujours de traductions à jour immédiatement après la fusion des modifications de contenu.

Conseil : C'est le mode que nous vous recommandons de viser. Il nécessite un moteur de localisation IA bien configuré pour assurer une localisation parfaite. L'avantage est qu'il conduit à zéro intervention manuelle, car les traductions manquantes sont automatiquement vérifiées et complétées avant chaque déploiement en production.

Scénario 2 : Mises à jour des pull requests (commits directs)

Déclencheur : Pull request ouverte ou mise à jour avec des modifications de contenu Action : Commit les mises à jour de traduction directement sur la branche de la pull request

on:
  pull_request:
    types: [opened, synchronize]

# L'action commit directement sur la branche de la PR

- uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Flux : Modifications de contenu dans la branche PR → L'action commit les traductions vers la même branche PR

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

Scénario 3 : Pull requests vers la branche principale (mode pull request)

Déclencheur : Push vers la branche principale (par exemple, lors de la fusion des pull requests) Action : Crée une pull request avec les mises à jour de traduction

on:
  push:
    branches: [main]

# L'action crée une PR : main/lingo.dev → main

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true

Flux : Modifications de contenu poussées vers main → L'action crée la branche main/lingo.dev → Ouvre une PR de main/lingo.dev → main

Scénario 4 : Pull Requests vers des branches de fonctionnalités (Mode Pull Request)

Déclencheur : Pull request ouverte ou mise à jour avec des modifications de contenu Action : Crée une pull request avec des mises à jour de traduction ciblant la branche de fonctionnalité

on:
  pull_request:
    types: [opened, synchronize]

# L'action crée une PR : feat/new-feature/lingo.dev → feat/new-feature

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true

Flux : Modifications de contenu dans feat/new-feature → L'action crée la branche feat/new-feature/lingo.dev → Ouvre une PR de feat/new-feature/lingo.dev → feat/new-feature

Cela maintient des révisions de traduction séparées pour chaque branche de fonctionnalité.

Convention de nommage des branches

En utilisant le mode pull request, l'Action GitHub Lingo.dev suit un modèle de nommage cohérent :

Format : <branche-base>/lingo.dev

Exemples :

Mises à jour de la branche principale : main/lingo.dev → main
Mises à jour de branches de fonctionnalités : feat/user-auth/lingo.dev → feat/user-auth
Mises à jour de branches de version : release/v2.0/lingo.dev → release/v2.0

Cette convention de nommage garantit que les branches de traduction sont clairement identifiables et automatiquement liées à leurs branches sources.

Gérer les contributions externes

Lors du travail avec des forks externes, implémentez un checkout sélectif pour maintenir la sécurité du dépôt :

jobs:
  i18n:
    name: Run i18n
    runs-on: ubuntu-latest
    permissions:
      actions: write
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - run: find locales/** -name "*.json" | xargs git checkout ${{ github.event.pull_request.head.sha }} --
        shell: bash
      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Permissions requises pour les contributions externes

La gestion des forks externes nécessite des permissions élevées pour traiter en toute sécurité les contributions :

permissions:
  actions: write # Requis : Accès aux informations de workflow et aux artefacts
  contents: write # Requis : Création de commits et accès au contenu du dépôt
  pull-requests: write # Requis : Mise à jour des pull requests provenant de forks externes

La permission actions: write est spécifiquement nécessaire pour :

Accéder aux métadonnées des pull requests provenant de forks externes
Lire le contexte du workflow pour la validation de sécurité
Gérer les artefacts et l'état du workflow de manière sécurisée

Ces permissions élevées garantissent que l'action peut traiter en toute sécurité les traductions provenant de contributeurs externes tout en maintenant la sécurité du dépôt grâce à un checkout sélectif des fichiers.

Cette approche :

Ne récupère que les fichiers de traduction du fork
Empêche l'exposition du code sensible du dépôt
Maintient les permissions d'écriture nécessaires pour l'action

Configuration avancée

Personnalisez le comportement de l'action en utilisant des paramètres supplémentaires :

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true
    commit-message: "feat: mise à jour des traductions via lingo.dev"
    working-directory: "apps/web"
    version: "latest"
    process-own-commits: false
    parallel: true

Options de configuration :

commit-message — Message personnalisé pour les commits de traduction
working-directory — Exécuter l'action dans un sous-répertoire
version — Fixer une version spécifique du CLI (non recommandé)
process-own-commits — Traiter les commits effectués par cette action
parallel — Activer le traitement parallèle des tâches de localisation (par défaut : false)

Traitement parallèle

L'Action GitHub prend en charge le traitement parallèle des tâches de localisation pour accélérer significativement les flux de travail de traduction pour les grands projets. Activez cette fonctionnalité en définissant parallel: true :

- uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    parallel: true

Lorsqu'elle est activée, l'action :

Distribue les tâches de localisation entre plusieurs workers concurrents
Utilise des algorithmes intelligents de distribution des tâches pour maximiser le débit
Prévient la corruption des fichiers et les conditions de concurrence grâce à une gestion minutieuse de la concurrence
Réduit considérablement le temps de traitement pour les projets comportant de nombreux fichiers de traduction

Cette fonctionnalité est particulièrement avantageuse pour :

Les grands projets avec des besoins étendus en traduction
Les flux de travail traitant plusieurs locales simultanément
Les équipes nécessitant une exécution plus rapide des pipelines CI/CD

Remarque : Le traitement parallèle peut augmenter l'utilisation de l'API. Surveillez votre utilisation si vous avez des limites de taux strictes.

Mode de vérification

En utilisant l'option --frozen, vous pouvez vérifier que toutes les traductions sont à jour avant chaque déploiement en production.

Voici un exemple d'utilisation de l'option --frozen dans votre pipeline de déploiement :

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx lingo.dev@latest i18n --frozen
      - run: npm run build
      - run: npm run deploy

L'option --frozen :

Vérifie que toutes les traductions sont à jour
N'apporte aucune modification aux fichiers
Fait échouer le build si des traductions sont manquantes ou obsolètes