i18n-radar: Type-Safe i18n Denetimi: Statik Analiz Yaklaşımı

Büyük ölçekli Frontend mimarilerinde (özellikle Arapça-İngilizce gibi çift yönlü/RTL desteği gerektiren projelerde), uluslararasılaştırma (i18n) süreçleri genellikle CI/CD boru hattının en zayıf halkasıdır.

4 yıllık Enterprise proje deneyimimde tekrar tekrar karşılaştığım temel problem şuydu: Çeviri bütünlüğü (translation integrity) genellikle runtime'a bırakılıyor.

Bu reaktif yaklaşım, production ortamında eksik anahtarlar (missing keys) veya kritik parametre uyuşmazlıkları nedeniyle UI kırılmalarına yol açıyor. Standart linter'lar sözdizimini denetlese de, dosya sistemine dağılmış yüzlerce parçalı çeviri dosyasının mantıksal tutarlılığını denetleyemiyor.

Bu mühendislik problemini çözmek için, build-time aşamasında çalışan, format bağımsız bir statik analiz aracı olan i18n-radar'ı geliştirdim.

Teknik Darboğaz: Dağınık Yapılar ve Parametre Güvenliği

Modern mimarilerde (Domain-Driven veya Feature-Based), çeviri dosyaları merkezi değildir; bileşenlerle birlikte yaşarlar (Colocation). Mevcut araçların yetersiz kaldığı noktalar şunlardı:

1. Split-File Mimarisi: Binlerce parçaya bölünmüş .ts veya .json dosyalarını efektif bir şekilde haritalayamamaları.
2. Tip Güvenliği Eksikliği: Mantıksal hataların yakalanamaması. Örneğin; "Base" dilde {name} parametresi varken, "Target" dilde bunun unutulması veya yanlışlıkla {user} olarak isimlendirilmesi.
3. AST Analizi Kısıtı: TypeScript çeviri dosyalarındaki dinamik yapıların statik olarak analiz edilememesi.

Mühendislik Çözümü: i18n-radar

Geliştirdiğim çözüm, CI/CD boru hattına entegre olan ve "Base Language" yapısını "Source of Truth" (Tek Gerçeklik Kaynağı) olarak kabul eden bir CLI aracıdır.

Temel Mimari Kararlar:

• Runtime Compilation (Jiti): Sadece statik JSON'ları değil, TypeScript ve JavaScript dosyalarını da çalışma anında derleyerek analiz edebilmek için jiti entegrasyonu sağladım. Bu, aracı kullanılan framework'ten tamamen bağımsız hale getirdi.
• High-Performance Globbing: Monorepo'lardaki karmaşık, iç içe geçmiş klasör yapılarını (örn: src/**/{lang}.ts) desteklemek için yüksek performanslı glob eşleştirme algoritmaları kullandım.
• Context-Aware Diffing Algorithm: Basit bir string karşılaştırması yerine, enterpolasyon parametrelerini ayrıştıran (parsing) özel bir algoritma geliştirdim. Araç, geliştiriciye anlamsal raporlama yapar: "Hedef dilde {name} parametresi bekleniyordu, ancak {user} bulundu." Bu, debug süresini ciddi oranda düşürür.
• Developer Experience (DX): Terminal çıktısını, yüzlerce hata olsa bile okunabilir kılmak için katlanabilir bir "Tree View" raporlama yapısı tasarladım.

Sonuç ve ROI (Yatırım Getirisi)

i18n-radar'ın geliştirme iş akışına entegrasyonun olası kazançları:

• Çeviri kaynaklı regresyon hatalarının production'da %0'a inmesi.
• Code Review süreçlerinde manuel i18n kontrolü eforunun otomatize edilmesi.
• Proje ölçeği ne olursa olsun katı bir tip güvenliği sağlanması.

Bu araç şu an NPM üzerinde açık kaynak olarak yayınlanmıştır ve modern TypeScript/JavaScript ortamlarına kolayca entegre edilebilir.

• 🔗 GitHub & Kaynak Kod: github.com/berkinduz/i18n-radar
• 🔗 npm package: i18n-radar