Translation Sync Engine — better-i18n Yerelleştirme Pipeline'ınız için Güvenilir Async İşleme
Kaynak kodunuzu, çevirilerinizi ve CDN'inizi mükemmel senkronizasyonda tutan güvenilir, asenkron bir çeviri pipeline'ı — çakışma tespiti, activity logging ve sıfır veri kaybıyla.
Neden Özel bir Sync Engine?
Çeviri iş akışları birden fazla sisteme dokunur — Git repository'niz, bir çeviri veritabanı, çalışma zamanı teslimatı için CDN ve bağlam analizi için yapay zeka hizmetleri. Bu sistemleri gerçek zamanlı olarak koordine etmek kırılgandır. Tek bir API zaman aşımı, çevirilerinizi tutarsız bir durumda bırakabilir.
Better i18n, Cloudflare Queues üzerine inşa edilmiş özel bir Sync Engine ile bunu çözer. Key içe aktarmadan çevirileri yayımlamaya kadar her işlem, yeniden denemeler, sıralama garantileri ve tam gözlemlenebilirlik ile bir async job olarak işlenir.
Sonuç: Çevirileriniz, bir şeyler ters gitse bile tüm sistemlerde tutarlı kalır.
Mimari Genel Bakış
Sync Engine, yapılandırılmış mesajları işleyen bir Cloudflare Queue tüketicisidir. Her mesaj, tetiklenecek bir Sync, yüklenecek bir dosya, yayımlanacak bir batch gibi ayrı bir iş birimini temsil eder.
Mesajlar iyi tanımlanmış bir yaşam döngüsü boyunca akar:
- Producer — Eyleminiz (Push olayı, manuel Sync, yayımlama) bir mesajı kuyruğa ekler
- Queue — Cloudflare Queues dayanıklı, sıralı teslimat sağlar
- Consumer — Sync worker mesajı alır ve job'ı çalıştırır
- Activity Log — Her adım tam izlenebilirlik için bir Sync aktivitesi olarak kaydedilir
Bu ayrım, API yanıtlarınızın hızlı olduğu anlamına gelir (iş arka planda gerçekleşir) ve hatalar kullanıcı müdahalesi olmadan otomatik olarak yeniden denenir.
10 Mesaj Türü
Sync Engine, her biri belirli bir iş sınıfından sorumlu olan 10 farklı mesaj türünü işler:
| Mesaj Türü | Amaç |
|---|---|
| SYNC_START | Tam veya artımlı GitHub Sync'i tetikler — dosyaları getirir, Key'leri karşılaştırır, veritabanını günceller |
| REPO_PUSH_SYNC | GitHub Push Webhook olaylarını işler — hızlı artımlı Sync için yalnızca değiştirilen dosyaları işler |
| CDN_SETUP | Bir proje ilk yapılandırıldığında başlangıç CDN manifestini ve boş dil dosyalarını oluşturur |
| CDN_UPLOAD | R2 depolama alanına tek bir JSON çeviri dosyası yükler |
| CDN_MERGE | Değiştirilmemiş Key'lerin üzerine yazmadan mevcut bir CDN dosyasına yeni çeviri içeriğini birleştirir |
| CDN_CLEANUP | Bir projenin tüm R2 dosyalarını kaldırır (proje silinmesi veya sıfırlanması sırasında kullanılır) |
| AI_CONTEXT_ANALYSIS | Çeviri bağlamı oluşturmak için Firecrawl + Gemini ile web sitenizi analiz eder |
| REPO_ANALYSIS | Framework'leri tespit etmek, terminolojiyi çıkarmak ve proje bağlamı oluşturmak için GitHub repository'nizi tarar |
| PUBLISH_BATCH | Onaylanan çevirileri tek bir atomik işlemde hem CDN'e hem de GitHub'a gönderir |
| GLOSSARY_SYNC | Tutarlı makine çevirisi için terminoloji sözlüklerini DeepL ile senkronize eder |
Her mesaj türünün kendi işleyicisi, doğrulaması ve hata kurtarma mantığı vardır. CDN yükleme hatası hiçbir zaman bir Sync işlemini engellemez ve bunun tersi de geçerlidir.
Tam Yaşam Döngüsü Kapsamı için 12 Job Türü
Job'lar, birden fazla mesaj üretebilecek üst düzey iş akışlarını temsil eder:
- initial_import — Repository'nizden ilk kez Key çıkarma
- incremental_sync — Son çalıştırmadan bu yana yalnızca değiştirilen dosyaları senkronize etme
- full_sync — Tüm çeviri dosyalarının tam yeniden senkronizasyonu
- source_sync — Yalnızca kaynak dil değişikliklerini senkronize etme
- bulk_translate — Birden fazla dil için makine çevirisini tetikleme
- publish / batch_publish — Onaylanan çevirileri üretime gönderme
- cdn_upload / cdn_merge / cdn_setup / cdn_cleanup — CDN yaşam döngüsü işlemleri
- glossary_sync — DeepL sözlüklerini güncel tutma
Job türleri size ayrıntılı kontrol sağlar. Tam olarak ihtiyacınız olan iş akışını tetikleyebilirsiniz — gereksiz işlem yok, boşa harcanan hesaplama yok.
Tam Gözlemlenebilirlik için 45'ten Fazla Activity Action
Her Sync Job, ilerledikçe yapılandırılmış Activity Action'ları kaydeder. 45'ten fazla farklı eylem türüyle, ne olduğu, ne zaman ve neden olduğu hakkında eksiksiz bir resim elde edersiniz.
Tipik bir Sync akışı şu aktivite izini üretir:
SYNC_STARTED → FETCH_FILES → FILES_FETCHED → COMPARE_KEYS →
UPDATE_DATABASE → PR_GENERATION_STARTED → PR_CREATED → SYNC_COMPLETED
Activity Action'lar yalnızca hata ayıklama için değildir — gerçek zamanlı Sync durumu arayüzünü güçlendirerek ekibinizin bir Sync'in yaşam döngüsünde tam olarak nerede olduğunu görmesini sağlar. Bir şey başarısız olursa, son kaydedilen eylem size tam olarak neyin yanlış gittiğini söyler.
Çakışma Tespiti ve Çözümü
Birden fazla kaynak aynı çeviri Key'ini değiştirdiğinde çakışmalar kaçınılmazdır. Sync Engine bunu özel bir çakışma tespiti ve çözüm sistemiyle yönetir.
Çakışmalar Nasıl Tespit Edilir
Her Sync sırasında Engine, gelen değişiklikleri mevcut veritabanı durumuyla karşılaştırır. Son Sync'ten bu yana hem repository'de hem de veritabanında bir Key değiştirilmişse, çakışma olarak işaretlenir.
Çakışmalar Nasıl Çözülür
Çakışmalar, ekibinize tam bağlamla gösterilir — kaynak değer, veritabanı değeri ve her değişikliğin zaman damgaları. Çakışmaları tek tek veya toplu olarak çözebilirsiniz:
- Kaynağı koru — Repository sürümünü kabul et
- Veritabanını koru — Mevcut çeviriyi sakla
- Manuel birleştirme — Son değeri kendiniz düzenleyin
Engine hiçbir zaman sessizce bir çeviriyi üzerine yazmaz. Her çakışma günlüğe kaydedilir, takip edilir ve açık bir çözüm gerektirir.
Tasarım Gereği Güvenilirlik
Sync Engine her katmanda güvenilirlik için inşa edilmiştir:
- Dayanıklı mesaj teslimi — Cloudflare Queues en az bir kez teslimatı garanti eder. Mesajlar, worker yeniden başlatmalarını ve altyapı arızalarını atlatır.
- Otomatik yeniden denemeler — Başarısız job'lar üstel geri çekilme ile yeniden denenir. Geçici hatalar (API zaman aşımları, hız sınırları) kendiliğinden çözülür.
- Idempotent işlemler — Her mesaj işleyicisi güvenli şekilde yeniden çalıştırılabilecek şekilde tasarlanmıştır. Yeniden denemeler hiçbir zaman yinelenen veri oluşturmaz.
- Sıralı işleme — Bir proje içindeki mesajlar sırayla işlenir ve ilgili işlemler arasındaki yarış koşullarını önler.
- Activity Logging — Her adım kaydedilir ve hata ayıklama ile uyumluluk için tam bir denetim izi sağlar.
Başlarken
Sync Engine, GitHub repository'nizi Better i18n'e bağladığınızda hemen çalışmaya başlar. Yapılandırılacak hiçbir şey yoktur — Sync'ler, CDN güncellemeleri ve çakışma tespiti otomatik olarak yönetilir.
Daha fazla kontrole ihtiyaç duyan ekipler için Sync Engine, belirli iş akışlarını tetiklemenize, ilerlemeyi izlemenize ve çakışmaları programatik olarak çözmenize olanak tanıyan job düzeyinde API'ler sunar.