← Retour au blog
A git diff view showing a locale file with three changed keys highlighted, and only those three keys being sent to the translation API below.

Vous n'avez pas besoin de tout retraduire : comment fonctionne la traduction delta dans CI

By Robert M

Vous n'avez pas besoin de tout retraduire : comment fonctionne la traduction delta dans le CI

Une fois que vous avez intégré la traduction automatisée dans votre pipeline CI, une question naturelle se pose rapidement : est-ce que cela retraduit tout le fichier de localisation à chaque fois que quelqu'un pousse un changement ?

Sans le mode delta, oui. Chaque push qui touche votre fichier source de localisation envoie tout le fichier à l'API, chaque clé, chaque chaîne, qu'elle ait changé ou non. Pour un petit projet en début de développement, cela va. Pour un projet mature avec des centaines de clés de traduction réparties sur 10 ou 20 langues, vous gaspillez des jetons sur des chaînes qui n'ont pas changé depuis la dernière exécution et vous récupérez une sortie identique pour ce privilège.

La traduction delta résout ce problème. Au lieu d'envoyer le fichier complet, l'Action compare votre fichier source actuel à une base de référence stockée, identifie uniquement les clés ajoutées ou modifiées, et n'envoie que celles-ci à l'API. La sortie pour les clés inchangées est prise à partir des fichiers traduits existants. L'utilisation des jetons diminue pour correspondre au travail réellement effectué.

Comment fonctionne la base de référence

Lorsque le mode delta s'exécute pour la première fois, ou lorsque vous forcez un rafraîchissement complet, l'Action traduit le fichier source complet et stocke une représentation JSON aplatie de celui-ci comme fichier de base dans votre dépôt. Lors des exécutions suivantes, l'Action charge cette base, la compare au fichier source actuel, et construit une charge utile contenant uniquement les clés modifiées.

Pour les fichiers de localisation JSON, la base est stockée sous .polylingo-baseline.json dans votre répertoire messages. Pour les fichiers YAML, elle est .polylingo-yaml-baseline.json dans votre répertoire locales. Pour les fichiers Laravel PHP lang, elle est .polylingo-laravel-php-baseline.json dans votre répertoire lang.

La base est commitée avec vos fichiers traduits afin qu'elle voyage avec le dépôt. Tout développeur qui clone le repo obtient la même base sur laquelle le pipeline travaille.

Ce qui compte comme un changement

Le diff opère sur la représentation aplatie des clés de votre fichier source. Les structures imbriquées sont aplaties en clés en notation pointée avant comparaison :

{
  "nav.home": "Accueil",
  "nav.about": "À propos de nous",
  "hero.title": "Bienvenue sur notre plateforme",
  "hero.cta": "Commencer"
}

Une clé est incluse dans la charge delta si :

  • Elle existe dans le fichier source actuel mais pas dans la base (clé nouvelle)
  • Elle existe dans les deux mais la valeur a changé (clé modifiée)

Les clés qui existent dans la base mais pas dans le fichier source actuel (clés supprimées) sont automatiquement retirées des fichiers traduits. Les clés identiques dans les deux sont complètement ignorées et leurs traductions existantes sont conservées.

À quoi cela ressemble en pratique

Supposons que vous avez un projet Next.js avec 200 clés de traduction dans messages/en.json, déjà traduites en 12 langues. Un développeur met à jour le texte de la section hero et ajoute deux nouvelles clés pour une annonce de fonctionnalité. Cela fait 4 clés modifiées sur 200.

Sans le mode delta, le pipeline envoie les 200 clés multipliées par 12 langues à chaque push. Avec le mode delta, il n'envoie que 4 clés. L'utilisation des jetons pour cette exécution est d'environ 2 % de ce qu'un traduction complète coûterait. Le pipeline est aussi plus rapide car il y a moins à envoyer et moins à attendre.

Sur un mois de développement régulier, les économies s'accumulent significativement. La plupart des pushs touchent une poignée de chaînes. La retraduction complète ne se produit que lorsque vous ajoutez une nouvelle langue ou réinitialisez explicitement la base.

Les trois Actions GitHub PolyLingo

Le mode delta est disponible dans les trois Actions de traduction PolyLingo. Chacune est construite pour un type de contenu et une structure de projet spécifiques.

translateAction — JSON et Markdown

L'Action originale. Gère les fichiers de localisation JSON plats dans le style next-intl et i18next, avec un passage optionnel de documentation Markdown via l'API async jobs pour les fichiers plus volumineux.

- uses: UsePolyLingo/translate-action@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    source_file: messages/en.json
    locales: fr,de,es,ja,zh
    delta: true
    commit: true
    commit_message: "chore(i18n): sync translations"

Base delta : messages/.polylingo-baseline.json

github.com/UsePolyLingo/translateAction — Voir sur Marketplace

translate-action-yaml — fichiers de localisation YAML

Pour les projets utilisant des fichiers de localisation YAML imbriqués : Rails i18n, Vue i18n, et tout autre framework utilisant le format YAML. L'Action gère automatiquement la convention Rails d'une clé racine locale — en.yml a une clé racine en:, et chaque fichier de sortie reçoit la bonne clé locale cible (fr:, de: etc).

Puisque l'API PolyLingo fonctionne nativement avec JSON, l'Action aplatit le YAML imbriqué en JSON en notation pointée avant envoi, traduit, puis reconstruit la structure imbriquée et écrit une sortie YAML valide. Une mise en garde v1 : les clés contenant naturellement des points ne sont pas supportées, car elles entrent en conflit avec l'aplatissement en notation pointée.

- uses: UsePolyLingo/translate-action-yaml@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    locales_dir: config/locales
    source_file: config/locales/en.yml
    locales: fr,de,es,ja
    delta: true
    commit: true

Base delta : config/locales/.polylingo-yaml-baseline.json

github.com/UsePolyLingo/translate-action-yaml — Voir sur Marketplace

translate-action-laravel — fichiers lang Laravel

Pour les projets Laravel utilisant soit des fichiers de traduction JSON (lang/en.json, supportant les structures imbriquées et plates dans le style Laravel 9+), soit des fichiers lang PHP tableau (lang/en/*.php). L'Action détecte automatiquement le format utilisé via php_format: auto — elle vérifie d'abord lang/en.json et revient aux fichiers PHP si non trouvé.

Pour les fichiers PHP, elle appelle le CLI PHP pour lire les fichiers source et sérialise la sortie traduite en syntaxe tableau PHP valide en JavaScript, sans dépendances supplémentaires. Les runners GitHub hébergés ubuntu-latest incluent PHP 8.x par défaut, donc aucune étape d'installation supplémentaire n'est nécessaire. PHP 7.4 ou plus récent est requis.

Une mise en garde v1 : les clés contenant des points ne sont pas supportées en mode PHP à cause de la stratégie d'aplatissement en notation pointée.

- uses: UsePolyLingo/translate-action-laravel@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    lang_dir: lang
    source_locale: en
    locales: fr,de,es,pt,nl
    php_format: auto
    delta: true
    open_pr: true

Base delta : lang/.polylingo-laravel-json-baseline.json ou lang/.polylingo-laravel-php-baseline.json selon le format.

github.com/UsePolyLingo/translate-action-laravel — Voir sur Marketplace

Mode PR vs mode commit

Les trois Actions supportent deux modes de sortie.

Mode commit (commit: true) écrit les fichiers traduits et les commit directement sur la branche courante. Configuration simple, bon pour les équipes qui considèrent la traduction comme un processus automatisé ne nécessitant pas de revue.

Mode PR (open_pr: true) crée une nouvelle branche (polylingo/yaml-<sha>, polylingo/laravel-<sha>, etc.), écrit les fichiers traduits là, et ouvre une pull request contre votre branche de base. Mieux pour les équipes qui veulent une étape de revue humaine avant la fusion du contenu traduit, ou pour les projets où la qualité de la traduction affecte directement l'expérience utilisateur.

Quand les deux sont activés, le mode PR l'emporte.

Le mode PR nécessite la permission pull-requests: write dans les permissions de votre workflow :

permissions:
  contents: write
  pull-requests: write

Forcer un rafraîchissement complet

Le mode delta compare avec la base stockée. Si vous voulez retraduire tout indépendamment de ce que montre la base, mettez delta: false. Cela met aussi à jour la base pour correspondre au fichier source actuel, donc les exécutions delta suivantes partent du nouvel état.

Un rafraîchissement complet est utile lorsque vous ajoutez une nouvelle langue cible, lorsque vous voulez bénéficier d'améliorations de qualité de traduction dans une nouvelle version du modèle, ou lorsque la base a dérivé de la réalité pour une raison quelconque.

- uses: UsePolyLingo/translate-action-yaml@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    locales_dir: config/locales
    locales: fr,de,es,ja,zh,ko,ar
    delta: false  # rafraîchissement complet, met à jour la base
    commit: true

Sorties pour les étapes en aval

Les trois Actions exposent les mêmes sorties pour que vous puissiez les utiliser dans les étapes suivantes du workflow :

- uses: UsePolyLingo/translate-action@v1
  id: translate
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    source_file: messages/en.json
    locales: fr,de,es
    delta: true
    commit: true

- name: Journaliser les statistiques de traduction
  run: |
    echo "Langues traduites : ${{ steps.translate.outputs.locales_translated }}"
    echo "Fichiers modifiés : ${{ steps.translate.outputs.files_changed }}"
    echo "Jetons utilisés : ${{ steps.translate.outputs.tokens_used }}"

Chaque exécution écrit aussi un tableau résumé dans le résumé de l'étape GitHub Actions pour que vous puissiez voir l'utilisation des jetons et les résultats de traduction sans fouiller dans les logs.

Pour commencer

Les trois Actions sont disponibles sur le GitHub Marketplace. Vous aurez besoin d'une clé API PolyLingo, disponible gratuitement sur usepolylingo.com. Le niveau gratuit inclut 50 000 jetons par mois. Avec le mode delta activé, la plupart des projets resteront bien en dessous de cette limite lors des pushs de développement réguliers.

Ajoutez votre clé API comme secret du dépôt (POLYLINGO_API_KEY) et insérez l'Action pertinente dans votre workflow. La première exécution fait une traduction complète et définit la base. Chaque exécution suivante ne traduit que ce qui a changé.