İçindekiler
API-First Lokalizasyon: Çeviriyi Geliştirme İş Akışınıza Entegre Etmek
Temel Çıkarımlar
- API-first lokalizasyon, manuel dosya alışverişinin yerini kod tabanınız ile çeviri yönetim sistemi arasındaki otomatik senkronizasyonla doldurur
- CLI araçları ve CI/CD entegrasyonları, her dağıtımda çevirilerin senkronize kalmasını sağlayan push/pull iş akışlarını mümkün kılar
- Webhook tabanlı bildirimler, çeviriler güncellendiğinde build'leri tetikler ve sürekli lokalizasyonu mümkün kılar
- API-first yaklaşımlar, yeni diller için pazara çıkış süresini haftalardan saatlere indirir
API-First Lokalizasyon Nedir?
API-first lokalizasyon, çeviri yönetim sisteminin (TMS) REST API'lar, CLI araçları ve webhook'lar aracılığıyla tüm çeviri iş akışlarına programatik erişim sağladığı bir yaklaşımdır. Çeviri dosyalarını manuel olarak dışa/içe aktarmak yerine, geliştiriciler çeviri senkronizasyonunu doğrudan build ve dağıtım pipeline'larına entegre eder.
Geleneksel ve API-First İş Akışı Karşılaştırması
Geleneksel (Dosya Tabanlı)
- Geliştirici kaynak stringleri bir dosyaya aktarır (JSON, XLIFF vb.)
- Dosya TMS'e yüklenir veya çevirmenlere e-postayla gönderilir
- Çevrilmiş dosyalar günler/haftalar sonra geri gelir
- Geliştirici dosyaları indirir ve doğru dizinlere yerleştirir
- Geliştirici commit'ler ve deploy eder
Sorunlar: Manuel adımlar, versiyon kayması, merge çakışmaları, yavaş döngü süreleri.
API-First
- Geliştirici yeni stringleri CLI ile gönderir:
better-i18n push - TMS çevirmenleri yeni içerik hakkında bilgilendirir
- Çevirmenler TMS editöründe tam bağlamla çalışır
- Çeviriler tamamlandığında webhook CI/CD'yi tetikler
- Build son çevirileri çeker:
better-i18n pull - Dağıtım güncellenmiş çevirileri otomatik olarak içerir
Faydalar: Manuel dosya işleme yok, sürekli senkronizasyon, daha hızlı döngü süreleri.
API-First Lokalizasyonun Temel Bileşenleri
REST API
TMS API'si şu endpoint'leri sağlar:
POST /api/keys — Yeni çeviri anahtarları oluştur GET /api/translations — Bir locale için çevirileri getir PUT /api/translations — Çevirileri güncelle GET /api/projects — Projeleri ve durumlarını listele POST /api/upload — Kaynak dosyaları yükle GET /api/download — Çevrilmiş dosyaları indir
CLI Aracı
Geliştirici kolaylığı için API'yi saran bir komut satırı aracı:
# Yeni kaynak stringleri TMS'e gönder better-i18n push # Son çevirileri çek better-i18n pull --locale=de,fr,ja # Çeviri durumunu kontrol et better-i18n status # Kod tabanını çevrilmemiş stringler için tara better-i18n scan
Webhook'lar
Çeviriler değiştiğinde olay güdümlü bildirimler:
{
"event": "translations.completed",
"project": "my-app",
"locale": "de",
"completed_keys": 142,
"total_keys": 142
}
CI/CD pipeline'larını, Slack bildirimlerini veya otomatik dağıtımları tetiklemek için webhook'ları kullanın.
CI/CD Entegrasyonu
Çeviri senkronizasyonunu build pipeline'ınıza entegre edin:
# GitHub Actions örneği
- name: Pull translations
run: better-i18n pull --all
env:
BETTER_I18N_TOKEN: ${{ secrets.BETTER_I18N_TOKEN }}
- name: Build
run: npm run build
API-First Lokalizasyonun Faydaları
| Fayda | Etki |
|---|---|
| Otomatik senkronizasyon | Manuel dosya yönetimi yok |
| Versiyon kontrolü | Çeviriler kodla birlikte takip edilir |
| Sürekli teslimat | Yeni çeviriler her dağıtımla birlikte yayınlanır |
| Geliştirici deneyimi | Tanıdık CLI/API iş akışı |
| Daha hızlı pazara çıkış | Yeni diller haftalar değil saatler içinde |
| Azaltılmış hatalar | Dosya biçimi sorunları veya yanlış yerleştirilmiş dosyalar yok |
Uygulama Kalıpları
Kalıp 1: Build Zamanı Pull
Build adımında çevirileri çekin. Çeviriler, build zamanında uygulamaya paketlenir.
En uygun: Statik siteler, önceden render edilmiş sayfalar, mobil uygulamalar.
Kalıp 2: Çalışma Zamanı Fetch
Çevirileri çalışma zamanında API'den getirin. Yeniden dağıtım gerektirmeden anında güncelleme sağlar.
En uygun: SPA'lar, dinamik web uygulamaları, gerçek zamanlı içerik.
Kalıp 3: Hibrit
İlk yükleme için build zamanında çevirileri çekin, acil düzeltmeler için çalışma zamanında güncellemeleri getirin.
En uygun: Hem performans hem esneklik gerektiren üretim uygulamaları.
SSS
API-first lokalizasyonu kullanmak için dosya biçimimi değiştirmem gerekiyor mu? Hayır. API-first TMS platformlarının çoğu standart biçimleri destekler (JSON, XLIFF, YAML, .strings, .xml) ve biçim dönüşümünü otomatik olarak gerçekleştirir.
Yeniden adlandırılan veya silinen çeviri anahtarlarını nasıl yönetirim? CLI scan komutu kullanılmayan anahtarları tespit eder. API endpoint'leri toplu anahtar işlemlerine olanak tanır. Çoğu TMS platformu anahtar yaşam döngüsünü takip eder ve yetim çevirileri işaretler.
Build sırasında API çalışmıyorsa ne olur? Yedek olarak önbelleğe alınmış çevirileri kullanın. Son başarılı pull'u versiyon kontrolünde saklayın; böylece API erişilemez olsa bile build'lerin her zaman bir temeli olur.
Birden fazla ortam için çevirileri nasıl yönetirim? Proje düzeyinde veya branch düzeyinde namespace kullanın. Bazı TMS platformları aynı proje için ortama özgü geçersiz kılmaları (staging, production) destekler.
API-first lokalizasyon küçük projeler için uygun mu? Evet. CLI push/pull iş akışı, birkaç yüz stringe sahip projeler için bile manuel dosya yönetiminden daha basittir. API entegrasyonunu kurmanın ek yükü, kazanılan zamana kıyasla minimumdur.
