better-i18n Doctor: Otomatik Çeviri Kalitesi İzleme

better-i18n Doctor: Otomatik Çeviri Kalitesi İzleme

Uygulamanız on iki dilde yayınlanıyor. Peki her ekranın, her hata mesajının, her araç ipucunun çevrildiğini nasıl biliyorsunuz? İngilizcedeki {count} yer tutucusunun Fransızcada yanlışlıkla {nombre} olarak yazılmadığını nasıl kontrol ediyorsunuz? Üç sprint önce kod tabanından sildiğiniz anahtarların hâlâ çeviri dosyalarınızda durup karışıklığa yol açmadığını nasıl anlıyorsunuz?

Çoğu ekip çeviri sorunlarını kullanıcılardan öğrenir. Tokyo'daki bir müşteri selamlama yerine dashboard.welcome_message gibi ham bir anahtar görür. Alman bir kullanıcı fiyatın gerçek tutar yerine {amount} olarak göründüğünü bildirir. Bir QA mühendisi JSON dosyalarını manuel olarak karşılaştırır ve İspanyolca çevirisinde geçen ay eklenen 47 anahtarın eksik olduğunu keşfeder.

better-i18n Doctor, kod tabanınızı ve çeviri dosyalarınızı tarayan, her kategorideki çeviri sorununu tespit eden ve 0-100 arasında bir sağlık puanı üreten otomatik bir i18n sağlık kontrolü aracıdır. CLI aracılığıyla yerel olarak çalışır, CI/CD pipeline'ınıza entegre edilir ve zaman içindeki takip için better-i18n platformuna sonuçları raporlar.

Sağlık Puanı Nasıl Çalışır

Doctor, 0 ile 100 arasında tek bir sayı olan sağlık puanı üretir. Bu puan, i18n kalitesinin farklı boyutlarını değerlendiren dört kategorinin ağırlıklı ortalamasıdır.

Dört Kategori

Coverage, kodunuzda kullanılan her anahtarın tüm hedef dil dosyalarında var olup olmadığını ölçer. İngilizcede bulunup Japonca'da bulunmayan bir anahtar Coverage açığıdır. Coverage, çeviri sorunlarının en yaygın kaynağıdır. Yeni özellikler, hiç çeviriye gönderilmemiş anahtarlarla birlikte çıkar ya da bir geliştirici bir namespace'e anahtar ekleyip diğerlerine eklemeyi unutur.

Quality, çevirilerin içeriğini yapısal doğruluk açısından kontrol eder. Yer tutucu uyumsuzlukları birincil endişedir. İngilizce dize {count} ve {name} içeriyorsa Almanca çeviride tam olarak aynı yer tutucuların bulunması gerekir. Quality ayrıca boş çevirileri (anahtarlar var ama değerleri boş), UI düzenini bozabilecek aşırı uzun çevirileri ve kaynak dille aynı olan dizeleri (İngilizceden kopyalanmış çevrilmemiş içeriği gösterebilir) de kontrol eder.

Structure, çeviri dosyalarınızın organizasyonunu değerlendirir. Yetim anahtarları (çeviri dosyalarında var olan ancak kaynak kodda hiç referans verilmeyen anahtarlar) kontrol eder. Yetim anahtarlar zararsızdır ancak bakım yükü yaratır: çevirmenler hiçbir kullanıcının görmeyeceği dizeleri güncellemek için zaman harcar, geliştiriciler kullanılmayan özellikler için çevirileri incelemek zorunda kalır. Structure ayrıca tutarlı anahtar adlandırma, yinelenen anahtarlar ve namespace organizasyonunu da kontrol eder.

Code, kaynak kodunuzu uluslararasılaştırılması gereken sabit kodlu dizeler için AST düzeyinde analiz kullanarak tarar. JSX bileşenlerindeki kullanıcıya yönelik dizeleri, UI fonksiyonlarına iletilen şablon literallerini ve hata mesajları veya bildirimlerde kullanılan dize sabitlerini algılar. Bu kategori, i18n teknik borcunun en yaygın kaynağını yakalar: bir geliştirici daha sonra düzeltmeyi planlayarak hız için <p>{t('common.loading')}</p> yerine <p>Loading...</p> yazar. Doctor bu dizeleri yayına girmeden önce bulur.

Puan Hesaplama

Her kategori, geçen kontrol sayısının toplam kontrol sayısına oranına göre 0 ile 100 arasında bir alt puan üretir. Genel sağlık puanı ağırlıklı ortalamadır:

Coverage'ın en yüksek ağırlığa sahip olmasının nedeni, eksik çevirilerin en doğrudan kullanıcı etkisine sahip olmasıdır; ham anahtarlar veya geri dönüş dili kullanıcılara gösterilir. Code analizinin ağırlığının en düşük olmasının nedeni, sabit kodlu dizelerin kullanıcı deneyimini hemen bozmayan teknik borç olmasıdır (zamanla ele alınmalıdır).

Geçme/Kalma Eşiği

Genel puan 80 veya üzerinde olduğunda ve sıfır hata olduğunda (uyarıların aksine hatalar) tarama geçti olarak işaretlenir. Hatalar, doğrudan kullanıcıları etkileyen sorunlardır: tam özellikler için eksik çeviriler, çalışma zamanı hatalarına neden olacak yer tutucu uyumsuzlukları veya var olmayan namespace'lere başvuran anahtarlar. Uyarılar, kullanıcı deneyimini bozmayan ancak düzeltilmesi gereken sorunlardır: yetim anahtarlar, tutarsız adlandırma veya sabit kodlu dizeler.

Geçme eşiğini ekibinizin standartlarına göre yapılandırabilirsiniz:

bi18n doctor --threshold 90

Doctor'ı Yerel Olarak Çalıştırma

Temel Tarama

Proje kökünden tam bir sağlık kontrolü çalıştırın:

bi18n doctor

Doctor, better-i18n.yml yapılandırmanıza göre veya yaygın dizin yapılarını (locales/, messages/, i18n/, lib/l10n/) algılayarak otomatik olarak çeviri dosyalarınızı keşfeder. Kaynak dosyalarınızı anahtar kullanımı için tarar ve sağlık raporunu üretmek için her şeyi çapraz referanslar.

Çıktı, genel puanı, kategori dağılımlarını ve bireysel kural sonuçlarını gösteren yapılandırılmış bir rapordur:

i18n Doctor Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Overall Score: 87/100 ✓ PASSED

Coverage     92/100  ██████████████████░░  3 missing keys
Quality      85/100  █████████████████░░░  2 placeholder mismatches
Structure    78/100  ███████████████░░░░░  12 orphan keys
Code         90/100  ██████████████████░░  4 hardcoded strings

Errors: 0  Warnings: 21
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Hedefli Taramalar

Acil ihtiyaçlarınız için alakasız veya çok yavaş olan kategorileri atlayın:

# Kod analizini atla (daha hızlı tarama)
bi18n doctor --skip-code

# Sağlık/kalite kontrollerini atla (yalnızca Coverage ve Structure)
bi18n doctor --skip-health

# Senkronizasyon durum kontrollerini atla
bi18n doctor --skip-sync

# Ayrıntılı çıktı — yalnızca başarısızlıkları değil, tüm kural sonuçlarını göster
bi18n doctor --verbose

Bireysel Kontrol Komutları

Doctor, ayrı olarak da çalıştırılabilen birkaç kontrolü bir arada sunar:

# Tüm dillerde eksik çeviri anahtarlarını kontrol et
bi18n check:missing

# Kaynak kodda referans verilmeyen yetim anahtarları kontrol et
bi18n check:unused

# Tüm kontrolleri çalıştır (kod analizi olmadan doctor ile eşdeğer)
bi18n check

# Sabit kodlu dizeler için kaynak kodu tara
bi18n scan

# Senkronizasyon durumu — yerel dosyaları platform durumuyla karşılaştır
bi18n sync --dry-run

Her komut, belirli endişesine odaklanmış çıktı üretir; bu durum belirli bir sorun kategorisini düzeltirken kullanışlıdır.

CI/CD Entegrasyonu

GitHub Actions

Doctor, her pull request'te CI kontrolü olarak çalışacak şekilde tasarlanmıştır. --ci bayrağı, GitHub Actions'ın anlayacağı bir biçimde sonuçlar üretir ve sorunlar içeren dosyalarda satır içi ek açıklamalar oluşturur:

# .github/workflows/i18n-doctor.yml
name: i18n Health Check

on:
  pull_request:
    paths:
      - "locales/**"
      - "src/**"
      - "messages/**"

jobs:
  doctor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Bun
        uses: oven-sh/setup-bun@v2

      - name: Install dependencies
        run: bun install

      - name: Run i18n Doctor
        run: bunx @better-i18n/cli doctor --ci --threshold 80
        env:
          BETTER_I18N_API_KEY: ${{ secrets.BETTER_I18N_API_KEY }}

--ci bayrağı ayarlandığında Doctor:

• Tarama başarısız olursa (puan eşiğin altında veya hatalar varsa) 1 kodu ile çıkar; bu durum GitHub Actions kontrolünün başarısız olmasına neden olur
• GitHub Actions biçiminde ek açıklamalar çıktılar; böylece sorunlar PR diff'inde satır içi yorum olarak görünür
• GitHub Actions kontrolü çıktısında görünen bir özet üretir

GitHub Actions İş Akışının Otomatik Oluşturulması

İş akışı dosyasını manuel olarak yazmak istemiyorsanız better-i18n sizin için oluşturabilir. Platform panosunda Integrations, ardından GitHub Actions'a gidin ve Create Doctor Workflow'a tıklayın. Bu, projenizin ayarlarına göre önceden yapılandırılmış bir iş akışı dosyası içeren bir pull request oluşturur.

Otomatik oluşturulan iş akışı şunları içerir:

• Çeviri dosyası konumlarınızla eşleşen yol filtreleri
• Yapılandırılmış eşiğiniz
• API anahtarı kurulum talimatları
• Başarısızlık durumunda isteğe bağlı Slack bildirimi

Platforma Raporlama

Doctor --report bayrağı ve API anahtarıyla çalıştırıldığında tam raporu better-i18n platformuna gönderir:

bi18n doctor --report --api-key $BETTER_I18N_API_KEY

Rapor şunları içerir:

• Puan ve geçme/kalma durumu
• Kategoriye göre hata ve uyarı sayıları
• Etkilenen anahtarlar ve dosyaları içeren bireysel kural sonuçları
• Meta veriler: commit SHA, branch adı, taranan dosya sayısı, kontrol edilen anahtar sayısı, zaman damgası

Platforma gönderilen raporlar saklanır ve proje panosunda görüntülenir. Zaman içindeki puan eğilimlerini görüntüleyebilir, branchlar arasındaki raporları karşılaştırabilir ve hangi kategorilerin iyileştiğini veya kötüleştiğini takip edebilirsiniz.

CI Raporu Gönderme

CI ortamlarında PR'yi doğrularken raporu göndermek için --ci ve --report'u birleştirin:

- name: Run i18n Doctor
  run: bunx @better-i18n/cli doctor --ci --report --threshold 85
  env:
    BETTER_I18N_API_KEY: ${{ secrets.BETTER_I18N_API_KEY }}

Bu size iki geri bildirim döngüsü sağlar:

1. Anlık: PR kontrolü geçer veya başarısız olur; geliştiriciler satır içi ek açıklamaları görür
2. Geçmişe yönelik: Rapor, eğilim analizi ve ekip görünürlüğü için platformda saklanır

Kural Ayrıntıları

Doctor, her kategoride bir dizi kuralı değerlendirir. En etkili kurallar ve algıladıkları şeyler aşağıdadır.

Coverage Kuralları

missing-keys: Kaynak kodunuzda kullanılan her anahtar için tüm hedef dil dosyalarında çeviri olup olmadığını kontrol eder. Eksik anahtarlar en yaygın i18n sorunudur ve en çok kullanıcıya görünür olanıdır; ham anahtar adları veya geri dönüş dili gösterilir.

namespace-coverage: Kodunuzda başvurulan her namespace'in tüm hedef diller için karşılık gelen çeviri dosyalarına sahip olup olmadığını kontrol eder. Bir geliştirici t('checkout.confirm_order') ekleyebilir ancak checkout namespace dosyası Korece için mevcut olmayabilir.

Quality Kuralları

placeholder-mismatch: Kaynak ve hedef çeviriler arasındaki yer tutucuları karşılaştırır. en: "Hello {name}, you have {count} items" mevcutsa, diğer tüm dillerin çevirilerinde {name} ve {count} olup olmadığını kontrol eder. Fazladan veya eksik yer tutucular çalışma zamanı hatalarına veya ham yer tutucu söz diziminin görüntülenmesine neden olur.

empty-translation: Hedef dilde mevcut olan ancak boş dize değerine sahip anahtarlara bayrak koyar. Boş çeviriler genellikle gerçek çevrilmiş içerik sağlanmadan anahtarların programlı olarak eklenmesinin sonucudur.

source-identical: Kaynak dille karakter karakter özdeş olan çevirilere bayrak koyar. Bazı dizeler (marka adları, URL'ler, teknik terimler) diller arasında meşru biçimde özdeştir; ancak yüksek sayıda kaynak-özdeş dize genellikle çevrilmemiş içeriğe işaret eder.

Structure Kuralları

orphan-keys: Kaynak kodun hiçbir yerinde başvurulmayan çeviri dosyalarındaki anahtarları tanımlar. Yetim anahtarlar, özellikler kaldırıldığında ancak çeviri dosyaları temizlenmediğinde birikir. Çevirmen çabasını boşa harcar ve neyin aktif kullanımda olduğu konusunda karışıklığa neden olur.

duplicate-keys: Tek bir dosya veya namespace içinde aynı anahtarın birden fazla kez tanımlanmış olduğunu algılar. Yinelemeler öngörülemeyen davranışa neden olur; çeviri motoru bunlardan birini kullanır, ancak hangisini kullandığı uygulama ayrıntılarına bağlıdır.

naming-consistency: Anahtar adlarının tutarlı kalıpları izleyip izlemediğini kontrol eder. Çoğu anahtar snake_case kullanıyorsa camelCase kullanan bir anahtar işaretlenir. Tutarsız adlandırma, anahtarları bulmayı ve bakımını yapmayı zorlaştırır.

Code Kuralları

hardcoded-jsx: JSX öğelerindeki dize literallerini algılamak için AST ayrıştırma kullanır. <h1>Welcome</h1> işaretlenir; <h1>{t('welcome')}</h1> işaretlenmez. Bu kural JSX'i anlar ve CSS sınıf adları ve veri öznitelikleri gibi kullanıcıya yönelik olmayan dizeleri yoksayar.

hardcoded-template: Tost bildirimleri, uyarı iletişim kutuları, hata mesajları gibi genellikle kullanıcıya yönelik çıktı üreten fonksiyonlara iletilen dize literallerini algılar. showToast("Operation successful") işaretlenir.

hardcoded-constant: errorMessage, label, title, placeholder gibi kullanıcıya yönelik adlara sahip değişkenlere atanan ve çeviri fonksiyonlarına sarılmamış dize sabitlerini tanımlar.

Platform Panosu

--report aracılığıyla gönderilen raporlar better-i18n platform panosunda görselleştirilir.

Puan Eğilimleri

Zaman serisi grafik, zaman içindeki sağlık puanınızı gösterir. Her nokta, tarihe göre çizilmiş bir Doctor raporunu temsil eder. main ile özellik branchlarının sağlık yörüngesini görmek için branche göre filtreleyebilirsiniz. Eğilim çizgisi, i18n kalitesinin iyileşip iyileşmediğini, kararlı mı yoksa kötüleşip kötüleşmediğini görmeyi kolaylaştırır.

Kategori Dağılımı

Hangi kuralların geçtiğini ve hangilerinin başarısız olduğunu görmek için her kategoriye inin. Başarısız olan her kural için etkilenen belirli anahtarları ve dosyaları görebilirsiniz. Bir anahtara tıklayarak çeviri düzenleyicide açın; bir dosyaya tıklayarak onu deponuzun bağlamında görüntüleyin.

Projeler Arası Karşılaştırma

Birden fazla projesi olan kuruluşlar için pano, tüm projelerdeki sağlık puanlarını gösterir. Bu, hangi projelerin i18n ilgisine ihtiyaç duyduğunu belirlemek ve kuruluş genelindeki kalite standartlarını belirlemek için kullanışlıdır.

Uyarılar

Sağlık puanınız bir eşiğin altına düştüğünde bildirim almak için uyarılar yapılandırın:

• E-posta: Sağlık puanı değişikliklerinin haftalık özeti
• Slack: Rapor başarısız olduğunda anlık bildirim
• Webhook: İzleme yığınınız için özel entegrasyon

Pratik Örnekler

Örnek 1: Yayın Öncesi Eksik Çevirileri Tespit Etme

Ekibiniz 30 yeni çeviri anahtarı içeren yeni bir ödeme akışı ekledi. Geliştirici tüm anahtarları İngilizce dosyasına ekledi. Fransızca ve Almanca çeviriler istendi ancak henüz tamamlanmadı. Doctor olmadan bu durum Fransız ve Alman kullanıcılara ham anahtarlar görünecek şekilde yayına girer.

CI'da Doctor ile:

Coverage     60/100  ████████████░░░░░░░░  30 missing keys (fr, de)

Error: 30 keys missing in target languages
  checkout.confirm_order — missing in: fr, de
  checkout.payment_method — missing in: fr, de
  checkout.shipping_address — missing in: fr, de
  ... (27 more)

Result: FAILED (score 60, threshold 80)

PR engellenir. Geliştirici satır içi ek açıklamaları görür, çevirileri ister ve PR yalnızca çeviriler tamamlandıktan sonra merge edilir.

Örnek 2: Yer Tutucu Uyumsuzluklarını Tespit Etme

Bir çevirmen bildirim dizesinin Almanca çevirisini günceller. İngilizce kaynak You have {count} new messages from {sender} içerir. Almanca çeviri yanlışlıkla {count} yerine {anzahl} kullanır.

Doctor bunu yakalar:

Quality      75/100  ███████████████░░░░░  1 placeholder mismatch

Error: Placeholder mismatch in notifications.new_messages (de)
  Source placeholders: {count}, {sender}
  Target placeholders: {anzahl}, {sender}
  Missing: {count}
  Extra: {anzahl}

Örnek 3: Özellik Kaldırıldıktan Sonra Temizlik

Ekibiniz altı ay önce eski panoyu kaldırdı. Kod gitti ama çeviri dosyaları hâlâ legacy_dashboard namespace'i altında 85 anahtar içeriyor. Çevirmenler toplu çeviri geçişleri yaparken zaman zaman hiç kimsenin görmediği içeriği güncellemek için zaman harcıyor.

Doctor yetim anahtarları bulur:

Structure    65/100  █████████████░░░░░░░  85 orphan keys

Warning: 85 keys in namespace "legacy_dashboard" are not referenced in source code
  legacy_dashboard.welcome — not referenced
  legacy_dashboard.stats_header — not referenced
  legacy_dashboard.chart_title — not referenced
  ... (82 more)

Örnek 4: Sabit Kodlu Dizeleri Bulma

Yeni bir geliştirici ekibe katılır ve çeviri sistemini kullanmadan bir özellik yazar. Tüm dizeleri JSX'e doğrudan sabit kodlar:

// Doctor öncesi
<div>
  <h2>Account Settings</h2>
  <p>Manage your account preferences below.</p>
  <button>Save Changes</button>
</div>

Doctor her sabit kodlu dizeye bayrak koyar:

Code         40/100  ████████░░░░░░░░░░░░  3 hardcoded strings

Warning: Hardcoded string in JSX element (src/pages/Settings.tsx:15)
  <h2>Account Settings</h2>
  Suggestion: <h2>{t('settings.account_title')}</h2>

Warning: Hardcoded string in JSX element (src/pages/Settings.tsx:16)
  <p>Manage your account preferences below.</p>

Warning: Hardcoded string in JSX element (src/pages/Settings.tsx:17)
  <button>Save Changes</button>

Alternatiflerle Karşılaştırma

Manuel JSON Fark Karşılaştırma: Çeviri dosyalarını manuel olarak karşılaştıran ekipler Coverage sorunlarını yakalayabilir ancak diğer her şeyi gözden kaçırır; yer tutucu uyumsuzlukları, yetim anahtarlar, sabit kodlu dizeler. Manuel kontroller de hataya açıktır ve birkaç dilin ötesinde ölçeklenmez.

ESLint i18n Eklentileri: eslint-plugin-i18next gibi lint kuralları JSX'teki sabit kodlu dizeleri yakalar ancak çeviri dosyası kalitesini, diller arasındaki Coverage'ı veya yapısal sorunları kontrol etmez. Doctor, kod analizini dört kategoriden biri olarak içerir ve i18n sorunlarının tam spektrumunu kapsar.

Phrase QPS (Kalite Performans Puanı): Phrase bir çeviri kalite puanı sağlar ancak teknik kalite (eksik anahtarlar, yer tutucu uyumsuzlukları, yetim anahtarlar) yerine dilbilimsel kaliteye (dilbilgisi, terminoloji) odaklanır. Doctor, teknik boyuta odaklanır; çalışma zamanı hatalarına ve bozuk UI'lara neden olan sorunlara.

Otomatik Kontrol Yok: Pek çok ekibin hiç otomatik i18n kontrolü yoktur. Sorunlar kullanıcılar veya QA mühendisleri tarafından keşfedilir. Doctor, sorunları herhangi bir ortama ulaşmadan önce yakalayan kapsamlı otomatik kapsam sağlar.

Sıkça Sorulan Sorular

Doctor taraması ne kadar sürer? 10.000 anahtar, 8 dil ve 200 kaynak dosyası içeren bir projenin tipik taraması 10 saniyenin altında tamamlanır. Kod analizi (AST ayrıştırma) en yavaş kategoridur. Yalnızca Coverage ve kalite kontrollerine ihtiyaç duyduğunuzda daha hızlı taramalar için --skip-code kullanın.

Doctor'ı better-i18n platformuna bağlanmadan çalıştırabilir miyim? Evet. Doctor varsayılan olarak tamamen yerel olarak çalışır. --report bayrağı isteğe bağlıdır ve yalnızca eğilim takibi için platforma sonuçları göndermek istiyorsanız gereklidir.

Kod analizi hangi framework'leri destekler? Kod analizi şu anda React (JSX/TSX), Vue (SFC şablonları) ve Svelte bileşenlerini destekler. Angular desteği planlanmaktadır. Framework algılama, projenizin bağımlılıklarına göre otomatik olarak gerçekleşir.

Özel kurallar ekleyebilir miyim? Özel kurallar yol haritasında yer almaktadır. Şu anda kural ciddiyet seviyesini (hata ve uyarı) yapılandırabilir ve projeniz için geçerli olmayan belirli kuralları devre dışı bırakabilirsiniz.

Doctor monorepo'larla çalışır mı? Evet. Doctor, workspace'i bilinçli taramayı destekler. Workspace sınırlarını algılar ve her paketi bağımsız olarak tarar; paket başına rapor ve birleşik genel puan üretir.

GitHub Actions iş akışı oluşturma nasıl çalışır? better-i18n panosunda Create Doctor Workflow eylemi, GitHub API'sini kullanarak deponuzda önceden yapılandırılmış .github/workflows/i18n-doctor.yml dosyası içeren bir pull request oluşturur. İş akışını etkinleştirmek için PR'yi inceleyip merge edin.

i18n Sağlık İzlemenizi Başlatın

Çeviri sorunları kullanıcılar tarafından değil CI'da yakalanmalıdır. better-i18n Doctor, ekibinize i18n kalitesinin her boyutunu puanlayan ve bozuk çevirilerin yayına girmesini engelleyen sürekli, otomatik bir sağlık kontrolü sunar.

Ücretsiz denemenizi başlatın ve ilk Doctor taramanızı beş dakikadan kısa sürede çalıştırın.