CDN Delivery: better-i18n ile Dünya Genelinde Edge-Cached Çeviriler

CDN Delivery: better-i18n ile Dünya Genelinde Edge-Cached Çeviriler

better-i18n'de yayımladığınız her çeviri, Cloudflare'in küresel edge ağına deploy edilir. Uygulamanız çevirileri en yakın edge node'dan alır — kaynak sunucuya gidip gelme yok, çeviri güncellemeleri için uygulama yeniden deploy edilmesine gerek yok.

CDN URL Yapısı

Çeviriler, organizasyon, proje, dil (locale) ve namespace bilgilerini içeren öngörülebilir bir URL düzenini takip eder:

https://cdn.better-i18n.com/{org}/{project}/{locale}/{namespace}.json

Örnekler:

# İngilizce common namespace
https://cdn.better-i18n.com/acme/web-app/en/common.json

# Türkçe auth namespace
https://cdn.better-i18n.com/acme/web-app/tr/auth.json

# Fransızca navigation namespace
https://cdn.better-i18n.com/acme/web-app/fr/nav.json

Her namespace-locale kombinasyonu ayrı bir JSON dosyasıdır; böylece uygulamanız yalnızca ihtiyaç duyduğu çevirileri yükler. Bu URL yapısı kararlıdır ve önbelleğe alınabilir — CDN edge node'ları, tarayıcı önbellekleri ve service worker'lar bu yapıdan yararlanabilir.

Proje Manifestosu

CDN ayrıca projenizin dil yapılandırmasını içeren bir manifest dosyası da sunar:

https://cdn.better-i18n.com/{org}/{project}/manifest.json

Projedeki tüm locale'leri içeren languages dizisini döndürür. Expo SDK, çalışma zamanında mevcut dilleri otomatik olarak keşfetmek için bu yapıyı kullanır.

CDN İşlemleri

better-i18n, CLI, REST API ve MCP araçları üzerinden eksiksiz bir CDN yönetim işlemleri seti sunar.

Kurulum ve Kaldırma

Yükleme İşlemleri

Tekli Yükleme (cdn.upload)

CDN'e tek bir namespace-locale dosyası yükler:

# İngilizce common çevirilerini yükle
better-i18n cdn upload --locale en --namespace common

Bu işlem dosyayı R2'ye yazar ve o yola ait edge önbelleğini geçersiz kılar. Değişiklikler saniyeler içinde 300'den fazla edge node'a yayılır.

Toplu Yükleme (cdn.uploadBatch)

Tek bir işlemde birden fazla namespace-locale kombinasyonu yükler:

# İngilizce ve Türkçe için tüm namespace'leri yükle
better-i18n cdn upload-batch --locales en,tr --namespaces common,auth,dashboard

Toplu yükleme, birden fazla dosya yayımlarken tekil yüklemelerden çok daha hızlıdır. R2 yazma işlemlerini ve önbellek geçersiz kılmalarını gruplandırarak toplam yayılma süresini kısaltır.

Birleştirme İşlemleri

Merge, dosyanın tamamını değiştirmeden mevcut bir CDN dosyasındaki belirli key'leri güncellemenizi sağlar. Bu, artımlı çeviri güncellemeleri için kritik öneme sahiptir.

Birleştirme (cdn.merge)

# Güncellenmiş key'leri İngilizce common namespace ile birleştir
better-i18n cdn merge --locale en --namespace common --keys "welcome,nav.home"

Merge, mevcut dosyayı R2'den okur, key düzeyindeki değişiklikleri uygular ve sonucu geri yazar. Merge'e dahil edilmeyen key'ler değişmeden kalır. Bu, birden fazla ekip üyesi veya otomasyon pipeline'ı eş zamanlı yayımlarken kazara üzerine yazılmasını önler.

Birleştirme Önizlemesi (cdn.mergePreview)

Bir merge işleminin çalıştırılmadan önce ne üreticeğini önizler:

# Merge sonucunu uygulamadan önizle
better-i18n cdn merge-preview --locale en --namespace common --keys "welcome"

Eklenen, güncellenen ve değişmeyen key'leri gösteren bir diff döndürür. Değişiklikleri yayına almadan önce doğrulamak için CI pipeline'larında veya inceleme iş akışlarında kullanın.

Dosya Yönetimi

Tekrar Eden İçeriklerin Tespiti ve Temizliği

Çeviri projeleri zamanla tekrar eden içerikler biriktirir — özellikle namespace'ler yeniden düzenlendiğinde veya key'ler namespace'ler arasında taşındığında.

Tekrar Edenleri Tespit Et (cdn.detectDuplicates)

Projedeki tüm CDN dosyalarını tarar ve namespace'ler genelinde tekrar eden çeviri değerlerini tespit eder:

better-i18n cdn detect-duplicates

Farklı namespace'lerde aynı değeri paylaşan key'leri gösteren bir rapor döndürür. Bu, çevirileri ortak namespace'lerde birleştirmenize ve toplam CDN yük boyutunu azaltmanıza yardımcı olur.

Tekrar Edenleri Temizle (cdn.cleanupDuplicates)

Tespit edilen tekrar eden içerikleri birleştirme tercihlerinize göre otomatik olarak çözer:

# Tekrar edenleri common namespace'e taşı
better-i18n cdn cleanup-duplicates --target-namespace common

Bu geri alınamaz bir işlemdir — ne değişeceğini incelemek için önce cdn.detectDuplicates çalıştırın ve hedef namespace sonucunu doğrulamak için cdn.mergePreview kullanın.

Güncellemeler Nasıl Çalışır

1. Çevirileri düzenleyin — dashboard'da, REST API aracılığıyla veya MCP araçlarıyla
2. Yayımlayın — publishTranslations kullanarak; bu bir cdn_upload sync işlemi tetikler
3. CDN saniyeler içinde güncellenir — Cloudflare değişikliği tüm edge node'lara yayar
4. Uygulamanız değişiklikleri alır — sonraki çeviri fetch işleminde; yeniden deploy gerekmez

Daha ayrıntılı kontrol için, yalnızca değişen key'leri güncellemek amacıyla tam yükleme yerine cdn.merge kullanın. CDN deploy'larını bir inceleme adımının arkasına almak için CI pipeline'ınızda cdn.mergePreview ile birleştirin.

Framework Entegrasyonu

Web: Next.js, TanStack Start, Vite

Web SDK'ları (@better-i18n/next, @better-i18n/use-intl), i18n.config.ts dosyanıza göre CDN fetch işlemlerini otomatik olarak yönetir:

// i18n.config.ts
export const project = "acme/web-app";
export const defaultLocale = "en";

SDK, proje tanımlayıcısından CDN URL'sini çözer ve çalışma zamanında doğru namespace-locale dosyalarını getirir.

Mobil: Expo / React Native

@better-i18n/expo, CDN delivery'nin üzerine çevrimdışı öncelikli önbellekleme ekler:

import { initBetterI18n, storageAdapter } from '@better-i18n/expo';
import { MMKV } from 'react-native-mmkv';

const mmkv = new MMKV({ id: 'translations' });

await initBetterI18n({
  project: 'acme/mobile-app',
  i18n,
  defaultLocale: 'en',
  storage: storageAdapter(mmkv),
});

Önce ağ stratejisi:

1. CDN'den getir (en güncel çevirileri al)
2. Kalıcı önbelleğe geri dön (MMKV veya AsyncStorage)
3. Paketlenmiş statik veriye geri dön (isteğe bağlı)

Kullanıcı uygulamayı ağ bağlantısıyla açtıktan sonra çeviriler yerel olarak önbelleğe alınır. Uygulama bu noktadan itibaren tamamen çevrimdışı çalışır.

Herhangi Bir HTTP İstemcisi

CDN sade bir HTTPS endpoint'tir — SDK gerekmez:

curl https://cdn.better-i18n.com/acme/web-app/en/common.json

{
  "welcome": "Welcome to our app",
  "nav.home": "Home",
  "nav.settings": "Settings"
}

Herhangi bir dil veya platformdan kullanın: Swift, Kotlin, Go, Python, Ruby — HTTP isteği yapabilen her şey.

Altyapı

• Cloudflare Workers — Dünya genelinde 300'den fazla konumda edge computing
• Cloudflare R2 — Çeviri dosyaları için sıfır çıkış ücretiyle nesne depolama
• Otomatik yayılma — Değişiklikler saniyeler içinde tüm edge node'lara ulaşır
• DDoS koruması — Cloudflare ağına yerleşik
• TLS 1.3 — Tüm CDN istekleri şifrelenir
• Sıfır çıkış maliyeti — R2, trafik hacminden bağımsız olarak bant genişliği ücretlerini ortadan kaldırır

Namespace Organizasyonu

Yüklenecekleri kontrol etmek için çevirileri namespace'lere ayırın:

acme/web-app/
├── en/
│   ├── common.json      → Ortak UI metinleri
│   ├── auth.json        → Giriş, kayıt, şifre sıfırlama
│   ├── dashboard.json   → Dashboard'a özgü metinler
│   └── marketing.json   → Landing page içerikleri
├── tr/
│   ├── common.json
│   ├── auth.json
│   └── ...
└── manifest.json        → Proje dil yapılandırması

Uygulamanız yalnızca mevcut sayfa veya özellik için ihtiyaç duyduğu namespace'leri yükler. Giriş sayfası auth.json; dashboard ise dashboard.json yükler. Bu, paket boyutlarını küçük ve sayfa yüklemelerini hızlı tutar.

Birden fazla namespace'de aynı değerle görünen key'leri belirlemek için düzenli aralıklarla cdn.detectDuplicates kullanın — ardından cdn.cleanupDuplicates ile bunları common.json'a taşıyın.

Yayımlama Kontrolleri

CDN yalnızca yayımlanmış çevirileri sunar. Nelerin yayına gireceğini kontrol etmek için yayımlama pipeline'ını kullanın:

1. getPendingChanges — CDN'e deploy edilecekleri önizleyin
2. publishTranslations — Değişiklikleri deploy edin (tümünü veya belirli çevirileri)
3. cdn.mergePreview — Uygulamadan önce key düzeyinde merge sonuçlarını önizleyin
4. cdn.merge — Dosyanın tamamını değiştirmeden artımlı key güncellemeleri uygulayın
5. getSyncs / getSync — Deploy durumunu takip edin

Bu size aşamalı bir iş akışı sunar: bekleyen değişiklikleri önizleyin, merge sonuçlarını doğrulayın, yayımlayın ve deploy'u izleyin — uygulama koduna dokunmadan.

Başlangıç

1. Projenizi oluşturun — dash.better-i18n.com adresinde
2. CDN'i başlatın — R2 depolama ve edge yönlendirmesini yapılandırmak için cdn.setup
3. Çeviri ekleyin — dashboard, REST API veya MCP araçları aracılığıyla
4. Yayımlayın — CDN'e deploy etmek için
5. Entegre edin — @better-i18n/next, @better-i18n/use-intl, @better-i18n/expo veya doğrudan HTTP ile

Ücretsiz plan dahil tüm planlarda çeviriler CDN üzerinden sunulur.