Translation Sync Engine — Procesamiento Async Confiable para su Pipeline de Localización con better-i18n
Una pipeline de traducción async confiable que mantiene su código fuente, traducciones y CDN perfectamente sincronizados — con detección de conflictos, activity logging y cero pérdida de datos.
¿Por qué una Sync Engine dedicada?
Los flujos de trabajo de traducción tocan múltiples sistemas — su repositorio Git, una base de datos de traducciones, un CDN para entrega en tiempo de ejecución y servicios de IA para análisis de contexto. Coordinar estos sistemas en tiempo real es frágil. Un solo timeout de API puede dejar sus traducciones en un estado inconsistente.
Better i18n resuelve esto con una Sync Engine dedicada construida sobre Cloudflare Queues. Cada operación — desde importar keys hasta publicar traducciones — se procesa como un job async con reintentos, garantías de orden y observabilidad completa.
El resultado: sus traducciones permanecen consistentes en todos los sistemas, incluso cuando algo falla.
Resumen de arquitectura
La Sync Engine es un consumidor de Cloudflare Queue que procesa mensajes estructurados. Cada mensaje representa una unidad discreta de trabajo — un sync que activar, un archivo que cargar, un batch que publicar.
Los mensajes fluyen a través de un ciclo de vida bien definido:
- Producer — Su acción (evento push, sync manual, publicación) encola un mensaje
- Queue — Cloudflare Queues proporciona entrega duradera y ordenada
- Consumer — El worker de sync recoge el mensaje y ejecuta el job
- Activity Log — Cada paso se registra como actividad de sync para trazabilidad completa
Esta separación significa que sus respuestas de API son rápidas (el trabajo ocurre en segundo plano), y los fallos se reintentanautomáticamente sin intervención del usuario.
10 tipos de mensajes
La Sync Engine maneja 10 tipos de mensajes distintos, cada uno responsable de una clase específica de trabajo:
| Tipo de mensaje | Propósito |
|---|---|
| SYNC_START | Activa un sync completo o incremental de GitHub — obtiene archivos, compara keys, actualiza la base de datos |
| REPO_PUSH_SYNC | Maneja eventos webhook de push de GitHub — procesa solo archivos modificados para sync incremental rápido |
| CDN_SETUP | Crea el manifiesto CDN inicial y archivos de idioma vacíos cuando un proyecto se configura por primera vez |
| CDN_UPLOAD | Carga un único archivo JSON de traducción al almacenamiento R2 |
| CDN_MERGE | Fusiona nuevo contenido de traducción en un archivo CDN existente sin sobrescribir keys sin cambios |
| CDN_CLEANUP | Elimina todos los archivos R2 de un proyecto (usado durante eliminación o restablecimiento del proyecto) |
| AI_CONTEXT_ANALYSIS | Analiza su sitio web con Firecrawl + Gemini para construir contexto de traducción |
| REPO_ANALYSIS | Escanea su repositorio GitHub para detectar frameworks, extraer terminología y construir contexto del proyecto |
| PUBLISH_BATCH | Envía traducciones aprobadas tanto al CDN como a GitHub en una única operación atómica |
| GLOSSARY_SYNC | Sincroniza glosarios de terminología con DeepL para traducción automática consistente |
Cada tipo de mensaje tiene su propio handler, validación y lógica de recuperación de errores. Un fallo en la carga CDN nunca bloquea una operación de sync, y viceversa.
12 tipos de jobs para cobertura completa del ciclo de vida
Los jobs representan flujos de trabajo de nivel superior que pueden producir múltiples mensajes:
- initial_import — Extracción de keys por primera vez desde su repositorio
- incremental_sync — Sincronizar solo archivos modificados desde la última ejecución
- full_sync — Resincronización completa de todos los archivos de traducción
- source_sync — Sincronizar solo cambios en el idioma fuente
- bulk_translate — Activar traducción automática para múltiples idiomas
- publish / batch_publish — Enviar traducciones aprobadas a producción
- cdn_upload / cdn_merge / cdn_setup / cdn_cleanup — Operaciones del ciclo de vida CDN
- glossary_sync — Mantener actualizados los glosarios de DeepL
Los tipos de jobs le dan control granular. Puede activar exactamente el flujo de trabajo que necesita — sin procesamiento innecesario, sin cómputo desperdiciado.
45+ Activity Actions para observabilidad completa
Cada job de sync registra activity actions estructuradas a medida que avanza. Con más de 45 tipos de acciones distintos, obtiene una imagen completa de qué ocurrió, cuándo y por qué.
Un flujo de sync típico produce este rastro de actividad:
SYNC_STARTED → FETCH_FILES → FILES_FETCHED → COMPARE_KEYS →
UPDATE_DATABASE → PR_GENERATION_STARTED → PR_CREATED → SYNC_COMPLETED
Las activity actions no son solo para depuración — impulsan la interfaz de usuario de estado de sync en tiempo real, permitiendo a su equipo ver exactamente dónde se encuentra un sync en su ciclo de vida. Si algo falla, la última acción registrada le dice con precisión qué salió mal.
Detección y resolución de conflictos
Cuando múltiples fuentes modifican la misma key de traducción, los conflictos son inevitables. La Sync Engine maneja esto con un sistema dedicado de detección y resolución de conflictos.
Cómo se detectan los conflictos
Durante cada sync, el engine compara los cambios entrantes con el estado actual de la base de datos. Cuando una key ha sido modificada tanto en el repositorio como en la base de datos desde el último sync, se marca como conflicto.
Cómo se resuelven los conflictos
Los conflictos se muestran a su equipo con contexto completo — el valor fuente, el valor de la base de datos y los timestamps de cada cambio. Puede resolver conflictos individualmente o en lote:
- Mantener fuente — Aceptar la versión del repositorio
- Mantener base de datos — Preservar la traducción existente
- Fusión manual — Editar el valor final usted mismo
El engine nunca sobrescribe silenciosamente una traducción. Cada conflicto se registra, se rastrea y requiere resolución explícita.
Fiabilidad por diseño
La Sync Engine está construida para fiabilidad en cada capa:
- Entrega de mensajes duradera — Cloudflare Queues garantiza entrega al menos una vez. Los mensajes sobreviven a reinicios de workers y fallos de infraestructura.
- Reintentos automáticos — Los jobs fallidos se reintentan con backoff exponencial. Los errores transitorios (timeouts de API, límites de velocidad) se resuelven solos.
- Operaciones idempotentes — Cada message handler está diseñado para ejecutarse de forma segura nuevamente. Los reintentos nunca crean datos duplicados.
- Procesamiento ordenado — Los mensajes dentro de un proyecto se procesan en orden, previniendo race conditions entre operaciones relacionadas.
- Activity logging — Cada paso se registra, dándole un audit trail completo para depuración y cumplimiento.
Comenzar
La Sync Engine funciona de inmediato cuando conecta su repositorio GitHub a Better i18n. No hay nada que configurar — los syncs, las actualizaciones de CDN y la detección de conflictos se manejan automáticamente.
Para equipos que necesitan más control, la Sync Engine expone APIs a nivel de job que le permiten activar flujos de trabajo específicos, monitorear el progreso y resolver conflictos programáticamente.