Translation Sync Engine — Traitement Async Fiable pour votre Pipeline de Localisation avec better-i18n
Une pipeline de traduction async fiable qui maintient votre code source, vos traductions et votre CDN parfaitement synchronisés — avec détection des conflits, activity logging et zéro perte de données.
Pourquoi une Sync Engine dédiée ?
Les workflows de traduction touchent plusieurs systèmes — votre repository Git, une base de données de traductions, un CDN pour la livraison à l'exécution et des services IA pour l'analyse contextuelle. Coordonner ces systèmes en temps réel est fragile. Un simple timeout d'API peut laisser vos traductions dans un état incohérent.
Better i18n résout cela avec une Sync Engine dédiée construite sur Cloudflare Queues. Chaque opération — de l'importation de clés à la publication de traductions — est traitée comme un job async avec des tentatives, des garanties d'ordre et une observabilité complète.
Le résultat : vos traductions restent cohérentes dans tous les systèmes, même en cas de problème.
Vue d'ensemble de l'architecture
La Sync Engine est un consommateur de Cloudflare Queue qui traite des messages structurés. Chaque message représente une unité de travail discrète — un sync à déclencher, un fichier à télécharger, un batch à publier.
Les messages suivent un cycle de vie bien défini :
- Producer — Votre action (événement push, sync manuel, publication) met un message en file d'attente
- Queue — Cloudflare Queues assure une livraison durable et ordonnée
- Consumer — Le worker de sync récupère le message et exécute le job
- Activity Log — Chaque étape est enregistrée comme activité de sync pour une traçabilité complète
Cette séparation signifie que vos réponses API sont rapides (le travail se passe en arrière-plan), et les échecs sont retentés automatiquement sans intervention utilisateur.
10 types de messages
La Sync Engine gère 10 types de messages distincts, chacun responsable d'une classe spécifique de travail :
| Type de message | Objectif |
|---|---|
| SYNC_START | Déclenche un sync GitHub complet ou incrémental — récupère les fichiers, compare les clés, met à jour la base de données |
| REPO_PUSH_SYNC | Gère les événements webhook push de GitHub — traite uniquement les fichiers modifiés pour un sync incrémental rapide |
| CDN_SETUP | Crée le manifeste CDN initial et les fichiers de langues vides lors de la première configuration d'un projet |
| CDN_UPLOAD | Télécharge un seul fichier JSON de traduction vers le stockage R2 |
| CDN_MERGE | Fusionne le nouveau contenu de traduction dans un fichier CDN existant sans écraser les clés inchangées |
| CDN_CLEANUP | Supprime tous les fichiers R2 d'un projet (utilisé lors de la suppression ou de la réinitialisation du projet) |
| AI_CONTEXT_ANALYSIS | Analyse votre site web avec Firecrawl + Gemini pour construire le contexte de traduction |
| REPO_ANALYSIS | Scanne votre repository GitHub pour détecter les frameworks, extraire la terminologie et construire le contexte du projet |
| PUBLISH_BATCH | Envoie les traductions approuvées vers le CDN et GitHub en une seule opération atomique |
| GLOSSARY_SYNC | Synchronise les glossaires de terminologie avec DeepL pour une traduction automatique cohérente |
Chaque type de message a son propre handler, sa validation et sa logique de récupération d'erreurs. Un échec lors du téléchargement CDN ne bloque jamais une opération de sync, et vice versa.
12 types de jobs pour une couverture complète du cycle de vie
Les jobs représentent des workflows de plus haut niveau qui peuvent produire plusieurs messages :
- initial_import — Extraction initiale des clés depuis votre repository
- incremental_sync — Synchroniser uniquement les fichiers modifiés depuis la dernière exécution
- full_sync — Resynchronisation complète de tous les fichiers de traduction
- source_sync — Synchroniser uniquement les changements de la langue source
- bulk_translate — Déclencher la traduction automatique pour plusieurs langues
- publish / batch_publish — Envoyer les traductions approuvées en production
- cdn_upload / cdn_merge / cdn_setup / cdn_cleanup — Opérations du cycle de vie CDN
- glossary_sync — Maintenir les glossaires DeepL à jour
Les types de jobs vous donnent un contrôle granulaire. Vous pouvez déclencher exactement le workflow dont vous avez besoin — sans traitement inutile, sans calcul gaspillé.
45+ Activity Actions pour une observabilité complète
Chaque job de sync enregistre des activity actions structurées au fur et à mesure de sa progression. Avec plus de 45 types d'actions distincts, vous obtenez une image complète de ce qui s'est passé, quand et pourquoi.
Un flux de sync typique produit cette trace d'activité :
SYNC_STARTED → FETCH_FILES → FILES_FETCHED → COMPARE_KEYS →
UPDATE_DATABASE → PR_GENERATION_STARTED → PR_CREATED → SYNC_COMPLETED
Les activity actions ne sont pas seulement pour le débogage — elles alimentent l'interface utilisateur de statut de sync en temps réel, permettant à votre équipe de voir exactement où en est un sync dans son cycle de vie. En cas d'échec, la dernière action enregistrée vous indique précisément ce qui a mal tourné.
Détection et résolution des conflits
Lorsque plusieurs sources modifient la même clé de traduction, les conflits sont inévitables. La Sync Engine gère cela avec un système dédié de détection et de résolution des conflits.
Comment les conflits sont détectés
À chaque sync, le moteur compare les changements entrants avec l'état actuel de la base de données. Lorsqu'une clé a été modifiée à la fois dans le repository et dans la base de données depuis le dernier sync, elle est signalée comme un conflit.
Comment les conflits sont résolus
Les conflits sont présentés à votre équipe avec le contexte complet — la valeur source, la valeur de la base de données et les horodatages de chaque changement. Vous pouvez résoudre les conflits individuellement ou en masse :
- Conserver la source — Accepter la version du repository
- Conserver la base de données — Préserver la traduction existante
- Fusion manuelle — Modifier vous-même la valeur finale
Le moteur ne remplace jamais silencieusement une traduction. Chaque conflit est enregistré, suivi et nécessite une résolution explicite.
Fiabilité par conception
La Sync Engine est construite pour la fiabilité à chaque couche :
- Livraison de messages durable — Cloudflare Queues garantit une livraison au moins une fois. Les messages survivent aux redémarrages de workers et aux pannes d'infrastructure.
- Tentatives automatiques — Les jobs échoués sont retentés avec un backoff exponentiel. Les erreurs transitoires (timeouts API, limites de débit) se résolvent d'elles-mêmes.
- Opérations idempotentes — Chaque message handler est conçu pour être réexécuté en toute sécurité. Les tentatives ne créent jamais de données en double.
- Traitement ordonné — Les messages au sein d'un projet sont traités dans l'ordre, évitant les race conditions entre opérations liées.
- Activity logging — Chaque étape est enregistrée, vous donnant une piste d'audit complète pour le débogage et la conformité.
Démarrer
La Sync Engine fonctionne immédiatement lorsque vous connectez votre repository GitHub à Better i18n. Il n'y a rien à configurer — les syncs, les mises à jour CDN et la détection des conflits sont tous gérés automatiquement.
Pour les équipes qui ont besoin de plus de contrôle, la Sync Engine expose des API au niveau des jobs qui vous permettent de déclencher des workflows spécifiques, de surveiller la progression et de résoudre les conflits par programmation.