i18n Teknik Borcunun Gizli Maliyeti

Mühendisleriniz yavaş değil. Ürününüz fazla karmaşık değil. Yeni pazarlara açılmanız lokal başına 6 ay sürüyor çünkü üç yıl önce biri "Welcome back, {name}!" ifadesini doğrudan JSX içine sabit olarak yazdı — ve ardından bin kişi daha aynı şeyi yaptı.

Her mühendislik ekibi teknik borcu takip eder. Kod karmaşıklık metrikleri. Bağımlılık güncelleme birikimi. Test kapsamı eksiklikleri. Büyük ihtimalle ekibinizin SonarQube skorunu ezberden söyleyebilirsiniz.

Ama çoğu CTO'ya i18n borçlarını sorduğunuzda boş bir bakış alırsınız. Takip edilmiyor. Ölçülmüyor. Hiçbir dashboardda görünmüyor. Ve teknik borç tablonuzdaki pek çok maddeden daha sessizce, daha pahalıya mal oluyor.

Bu yazı o maliyetin rakamlarını ortaya koyuyor. Hayali rakamlar değil — kendi kod tabanınız için bir öğleden sonraya hesaplayabileceğiniz türden.

i18n teknik borcu gerçekte nasıl görünür

Teknik borcun klinik bir tanımı var: şu an pratik bir çözüm seçmenin gelecekte yaratacağı yeniden iş maliyeti. i18n'de bu pratik çözüm neredeyse her zaman aynı: çeviri altyapısını atla, stringleri sabit yaz, "sonra uluslararasılaştırırız."

Bariz borç: sabit kodlanmış stringler

JSX'inizdeki her <p>Submit</p> ifadesi, çevrilmeden önce elle çıkarılması gereken bir stringdir. Her alert('Are you sure?') çeviri sisteminizin dışında yaşayan, kullanıcıya görünen bir mesajdır.

İlk günden i18n gözetilerek yazılmamış 50.000 satırlık bir React kod tabanında string çıkarma aracı çalıştırın. Tipik olarak 3.000-8.000 sabit kodlanmış çevrilebilir string bulursunuz. Her birinin:

1. Belirlenmesi (kullanıcıya görünüyor mu?)
2. Bir çeviri anahtarına çıkarılması
3. t() çağrısıyla sarılması
4. Çeviri dosyasına eklenmesi
5. Her hedef lokal için çevrilmesi
6. Düzen ve kırpma açısından test edilmesi

gerekiyor.

Tam çıkarma döngüsü için string başına 10-15 dakika hesaplanırsa, 5.000 string 800-1.250 mühendislik saatine karşılık gelir. Bu, tek bir geliştiricinin 5-8 aylık zamanıdır. Kod yazılırken externalize etmek bedava olacak stringler için.

Görünmez borç: yapısal sorunlar

Sabit kodlanmış stringler bariz borçtur. Yapısal sorunlar daha kötüdür çünkü bileşik hâle gelirler:

Anahtar yapısı yok. Anahtarlar "submit_button" ve "submit_button_2" gibi düz stringlerdir. Hiyerarşi yok, namespace kuralı yok, özellik alanına göre toplu çeviri yapmanın yolu yok. Ödeme akışınızı çevirmeniz gerektiğinde, ödemeyle ilgili anahtarları filtreleyemezsiniz çünkü taksonomi yok.

String bağlamı yok. Çevirmenleriniz "Total" görüyor ve tahmin etmek zorunda kalıyor: bu bir tablo başlığı mı, buton etiketi mi, yoksa fatura kalemi mi? Almancada bunlar üç farklı kelimedir. Her anahtarda bağlam metaverisi olmadığında, çevirmenler zamanın %15-25'inde yanlış tahmin eder.

Çeviri hafızası yok. "Are you sure you want to delete this?" ifadesi uygulamanızda 12 kez geçiyor. Çeviri hafızası olmadan 12 kez ayrı ayrı çevrilir — farklı çevirmenler tarafından potansiyel olarak 12 farklı biçimde.

Otomasyon yok. Çeviri güncellemeleri; bir geliştiricinin JSON'u elle dışa aktarmasını, çevirmenlere e-postayla göndermesini, dosyayı geri beklemesini, elle içe aktarmasını ve PR oluşturmasını gerektiriyor. Her gidiş-dönüş 3-5 iş günü alıyor.

Organizasyonel borç

i18n borcunun en sinsi biçimi kodda değil, org chart'ta.

Sahiplik boşluğu. Mühendislik çeviriye sahip çıkmıyor — "bu bir içerik meselesi." Marketing teknik sistemi anlamıyor. Ürün yöneticileri çeviri kapsamını bir metrik olarak takip etmiyor. Boşluğa kimse sahip çıkmıyor.

Çeviri güncellemeleri için SLA yok. Yeni bir özellik İngilizce olarak yayınlanıyor ve kimse çeviriye başlamadan önce 2-4 hafta İngilizce olarak kalıyor. Uluslararası kullanıcılar, her sürümden sonra haftalarca yarı çevrilmiş bir arayüz görüyor — İngilizce butonlar Almanca etiketlerle karışık.

Bileşik bilgisizlik. Ekibe katılan her yeni mühendis gördüğü kalıpları kopyalar. Kod tabanında sabit kodlanmış stringler varsa, onlar da sabit kodlayacak. Borç, kadro sayısıyla doğrusal olarak büyür.

Ödediğiniz bedeli nasıl nicelleştirebilirsiniz

i18n borcu ölçülebilir. Maliyet kategorileri ve hesaplama yöntemleri şunlar.

Mühendislik zamanı vergisi

Stripe'ın 2023 mühendislik anketi, geliştiricilerin zamanlarının %23'ünü teknik borç görevlerine harcadığını ortaya koydu. McKinsey, BT bütçelerinin %20-40'ının yeni değer yaratılmadan önce borç bakımına gittiğini tahmin ediyor.

i18n özeline odaklanarak bir sprint boyunca şunları takip edin:

String çıkarma süresi. Geliştiriciler sabit kodlanmış stringleri t() çağrılarıyla sarmak için kaç saat harcadı? i18n'i sonradan entegre eden çoğu şirkette, göç sırasında geliştirici başına sprint başına bu süre 4-8 saattir.

Merge conflict çözme. Çeviriler repodaki JSON dosyalarında yaşıyorsa, kaç merge conflict lokal dosyalarını kapsıyordu? Her conflict çözme 15-30 dakika alır (JSON sözdizimini yeniden doğrulama, anahtar sıralamasını yeniden kontrol etme, çeviri CI'yı yeniden çalıştırma). 6 geliştiriciyle sprint başına 1-2 conflict bekleyin: 30-60 dakika.

Bağlam geçiş maliyeti. Bir geliştiricinin çevirmene arayüz bağlamını açıkladığı kaç Slack thread'i vardı? Her thread geliştirici için 15 dakikalık bir bağlam geçişidir: sprint başına 1-2 saat.

Deployment yükü. Deploymentlarınızın yüzde kaçı yalnızca çeviri değişiklikleri tarafından tetikleniyor? Çeviriler repoda yaşıyorsa, her kopya düzeltmesi tam CI/CD pipeline'ını tetikler. Bir ay boyunca takip edin. Sayı genellikle toplam deploymentların %15-25'idir.

Sürüm gecikmesi çarpanı

İşte matematiğin rahatsız edici hâle geldiği yer.

Ürününüzün 5 hedef lokali var. Her lokal, bir özelliğin yeni stringlerini çevirmek için ortalama 2 hafta gerektiriyor (manuel dışa aktarma → çeviri → içe aktarma → QA döngüsü hesaba katıldığında). Yılda 12 özellik yayınlıyorsunuz.

5 lokal × 2 haftalık gecikme × 12 sürüm = 120 lokal-hafta gecikmiş kullanılabilirlik.

Bu, uluslararası kullanıcıların her sürümden sonra 2 hafta boyunca eksik bir ürün gördüğü 120 haftadır. %40 uluslararası gelire sahip bir SaaS ürününde, her sürümden sonra 2 hafta boyunca kullanıcı tabanınızın %40'ı kötüleşmiş bir ürün deneyimliyor.

Bileşik etki acımasızdır. Her özellik yeni stringler ekliyor. Bir sonraki sürüm yayınlandığında önceki özelliğin çevirileri tamamlanmamışsa, çevirmenler artık aynı anda iki birikim üzerinde çalışıyor. Gecikme artıyor. Kalite düşüyor. Ekip köşeleri kesmaya başlıyor — "sadece İngilizce olarak yayınla, sonra çeviririz." Borç büyüyor.

Pazar fırsat maliyeti

CSA Research, çevrimiçi tüketicilerin %87'sinin yalnızca İngilizce olan bir web sitesinden satın almayacağını bildiriyor. Küresel yazılım yerelleştirme pazarı 2025'te 6,27 milyar dolar değerinde olup %12,4 CAGR ile büyümektedir (Meticulous Research).

Francızca çeviriyi sizden 3 ay önce yayınlayan rakip, yalnızca 3 ay boyunca Fransız kullanıcıları kazanmaz. Kulaktan kulağa iletişimi, uygulama mağazası yorumlarını, Fransızca arama sonuçlarındaki SEO sıralamasını da kazanır. 3 aylık gelir kaybetmiyorsunuz — tüm bir pazarda ilk oyuncu avantajını bırakıyorsunuz.

30 milyon dolar ARR'ye ve %30 uluslararası büyüme potansiyeline sahip bir SaaS ürününde, yeni lokal lansmanlarındaki 3 aylık gecikme, lokal başına yaklaşık 750.000 dolar ertelenmiş geliri temsil ediyor. Bu, bir slayta koymaya değer bir rakam.

i18n borcu neden normal teknik borçtan daha hızlı bileşik hâle gelir

Çoğu teknik borç doğrusaldır. Dağınık bir fonksiyon, onu kullanan geliştiricileri yavaşlatır. Güncelliğini yitirmiş bir bağımlılık, onu kullanan servisleri etkiler. Hasar alanı sınırlıdır.

i18n borcu çarpımsal. İşte nedeni.

Kötü mimarinin ağ etkisi

Paylaşılan bir bileşende eksik tek bir çeviri anahtarı, her lokalde tek bir kırık sayfa anlamına gelir. Yanlış çevrilmiş tek bir terim, onu kullanan her ekrana yayılır. Kötü yapılandırılmış tek bir namespace, her yeni anahtarın oluşturulmasını daha uzun süre alır.

Çarpım faktörü şudur: etkilenen string sayısı × lokal sayısı × lokal başına kullanıcı sayısı.

Tek bir mimari karar — "namespacesiz düz anahtarlar kullanalım" — binlerce string, onlarca lokal ve çeviri koduna dokunan her geliştirici üzerinde sürtüşme yaratır.

İşe alım çarpanı

Yeni mühendisler mevcut kalıpları kopyalar. Kod tabanınızda 500 sabit kodlanmış string varsa, yeni işe alınanlar da sabit kodlayacak. i18n sisteminin var olduğunu bilmiyorlar çünkü kimse onları konusunda eğitmedi. Her işe alımla birlikte borç büyür.

Önemli teknik borca sahip mühendislik ekipleri %25-35 daha yüksek işten ayrılma bildiriyor (Haystack Analytics 2024). Neden: geliştiriciler zamanlarını string çıkarmaya ve merge conflict çözmeye harcamak istemiyor. Özellik geliştirmek istiyorlar. Kod tabanınız i18n yükü nedeniyle her özelliği %30 daha uzun sürdürüyorsa, en iyi mühendisleriniz bunu yapmayan bir kod tabanı bulacak.

"Genişlemeden önce düzeltiriz" tuzağı

Bu en yaygın karar kalıbı — ve en pahalısı:

1. 1. Yıl: Ürün İngilizce olarak piyasaya çıkıyor. "Genişlemeden önce i18n ekleriz."

2. 2. Yıl: Ürün büyüyor. i18n önceliklendirmesi sürekli erteleniyor. Kod tabanı 5.000 sabit kodlanmış string biriktiriyor.

3. 3. Yıl: Satış ekibi Almanya'da bir müşteri adayı buluyor. Liderlik şöyle diyor: "Almanca ne kadar hızlı yayınlayabiliriz?"

4. Mühendislik cevabı: "Tüm stringleri çıkarmak, çeviri pipeline'ını kurmak, çevirmek ve QA yapmak için 6 ay."

5. Liderlik: "Bu çok yavaş. Sadece en görünür sayfaları manuel olarak çevirin."

6. Sonuç: Yarı çevrilmiş ürün. Tutarsız kalite. "Gerçek" i18n geçişi ertelenmeye devam ediyor.

7. yılda, uygun uluslararasılaştırmanın maliyeti "2 haftalık kurulum" (1. yılda yapılsaydı) yerine "6 aylık göç"e dönüştü (olgun bir kod tabanının yeniden düzenlenmesi). Teknik borç yalnızca birikmedi — bileşik hâle geldi.

Denetim: i18n borç skorunuzu bulmak

i18n borcunuzu tek bir sprintte ölçebilirsiniz. İşte nasıl.

Adım adım denetim süreci

1. Takip edilmeyen çevrilebilir stringleri sayın.

Kod tabanınızda AST tabanlı bir string çıkarma aracı çalıştırın:

# Better i18n CLI kullanarak
npx @better-i18n/cli scan

# Veya i18next projeleri için i18next-parser kullanın
npx i18next-parser

Çıktı, çeviri sisteminizin dışında kaç kullanıcıya yönelik string olduğunu söyler. Bu, ham çıkarma birikiminizdir.

2. Çeviri dosyası yapısını denetleyin.

Şu soruları yanıtlayın:

• Anahtarlar özellik/bileşen bazında mı organize edilmiş, yoksa düz mı?
• En büyük tek lokal dosyası ne kadar? (Tek dosyada > 500 anahtar varsa, namespace sorununuz var)
• Anahtarların bağlam açıklamaları var mı?
• Sözlük var mı?

3. Tür güvenliğini kontrol edin.

# Sahte bir anahtar ekleyin ve build'in bunu yakalayıp yakalamadığına bakın
t('this.key.definitely.does.not.exist');

Build geçiyorsa, derleme zamanı anahtar güvenliğiniz yok demektir. Her anahtar referansı çalışma zamanında bir kumardır.

4. Çeviri gecikmesini ölçün.

"Geliştirici yeni stringlerle PR birleştiriyor" ile "tüm lokaller için çeviriler production'da canlı" arasındaki süreyi takip edin. Referans değerler:

• Yeşil: < 24 saat (otomatik pipeline, CDN dağıtımı)
• Sarı: 1-5 gün (kısmen otomasyon, toplu işleme)
• Kırmızı: > 1 hafta (manuel iş akışı, deployment'a bağlı)

Borç seviyenizi puanlayın

Çoğunlukla Yeşil: i18n altyapınız sağlam. Optimizasyona odaklanın. Çoğunlukla Sarı: Borç birikmekte. Lokal eklemeden önce yapısal sorunları düzeltin. Çoğunlukla Kırmızı: Durun. Genişlemeden önce bunu düzeltin. Maliyet buradan yalnızca artacak.

Getiri: i18n borcunu ortadan kaldırmak ne kazandırır

Mühendislik hızının geri kazanılması

i18n altyapısı sağlam olduğunda:

• Yeni lokal ekleme bir mühendislik projesi değil, içerik görevi hâline gelir. 2.000 çevrilmiş İngilizce anahtara sahip bir ürüne Japonca eklemek: günler (çeviri süresi), aylar değil (göç süresi).
• Çeviri dosyalarında sıfır merge conflict. Anahtarlar repodaki JSON dosyalarında değil, bir platformda yaşıyor.
• Sıfır çalışma zamanı eksik anahtar hatası. TypeScript her yazım hatasını derleme zamanında yakalar.
• 30 saniyelik çeviri düzeltmeleri. Tek kelimelik bir düzeltme deployment olmadan CDN'e yayınlanır.

Pazara çıkış süresinin hızlanması

i18n borcu olan ile olmayan ekip arasındaki fark:

Ekip morali

Bunu ölçmek zor, küçümsemek kolay. Zamanlarının %20'sini çeviri tesisatıyla geçiren mühendisler işlerinden zevk almıyor. Bağlam olmadan çalışan çevirmenler daha düşük kalite üretiyor ve daha hızlı tükeniyor.

Altyapıyı düzeltin ve:

• Geliştiriciler t('checkout.submit') yazıyor ve çeviri lojistiği hakkında bir daha düşünmüyor.
• Çevirmenler her string için arayüz bağlamını görüyor ve ilk seferinde doğru çeviriler üretiyor.
• Ürün yöneticileri çeviri kapsamını bir e-tabloda değil, dashboardda takip ediyor.

90 günlük i18n borcu ödeme planı

1. Ay: Denetim ve ölçüm (kod değişikliği yok)

• String çıkarma denetimini çalıştırın. Sayıyı belgeleyin.
• 4 sprint boyunca çeviri gecikmesini takip edin. Ortalamayı belgeleyin.
• Lokal dosyaları kapsayan merge conflict sayısını sayın. Sıklığı belgeleyin.
• Yukarıdaki formülleri kullanarak maliyeti hesaplayın. Sayıyı liderliğe sunun.

Bu ay görünürlükle ilgili. Ölçemediğinizi düzeltemezsiniz.

2. Ay: Kanayan yarayı durdurun

• PR'larda yeni sabit kodlanmış stringleri engellemek için ESLint kuralı ekleyin. Yeni borç yok.
• CI'da AST taraması kurun. Her PR yeni/kullanılmayan anahtarları raporlar.
• En çok değiştirilen 5 dosyayı uygun i18n anahtar yapısına geçirin. Kalıbın işe yaradığını kanıtlayın.
• En önemli 40 alan teriminizle bir sözlük başlatın.

Bu ay kapsama ile ilgili. Göçü planlarken yeni borç biriktirmeyi durdurun.

3. Ay: Hızlandırın ve otomatikleştirin

• Kod tabanınızı CDN dağıtımlı bir çeviri platformuna bağlayın. Çevirileri repodan çıkarın.
• Katman 1 içerik (UI stringleri, hata mesajları, sistem bildirimleri) için AI çevirisini etkinleştirin. Bu, çeviri hacminizin %60-70'ini otomatik olarak karşılar.
• CI'da çeviri kapsam raporlaması kurun. Her PR şunu gösterir: "Bu değişiklik 15 lokalden 12'sinde çevrildi."
• Çıkarma birikimini başlatın. Sayfa trafiğine göre önceliklendirin: önce en yüksek trafikli sayfalar.

3. ayın sonunda şunları görmeniz gerekir:

• Kod tabanına giren sıfır yeni sabit kodlanmış string
• Yeni stringler için 24 saatin altında çeviri gecikmesi
• Çıkarma birikimi için net bir tükenme grafiği
• Göçü sürdürmeyi haklı kılan maliyet verileri

Matematik açık

i18n teknik borcu, ölçene kadar görünmez. Sonra açıkça ortada.

İlk günden i18n altyapısını kuran ekip, onu sürdürmek için haftada 2 saat harcıyor. i18n'i 2 yıllık büyümenin ardından yeniden entegre eden ekip, geçiş için 6 ay harcıyor — ve altyapı yetenekler yerine kısıtlamalar gözetilerek tasarlandığı için süregelen bakım da daha yüksek kalıyor.

Kod tabanınızda 1.000'den fazla kullanıcıya yönelik string varsa ve 2'den fazla lokale hizmet ediyorsanız (veya etmeyi planlıyorsanız), i18n borcunuzu düzeltmenin ROI'si aylarla değil, haftalarla ölçülür.

Beklediğiniz her sprint, borç bileşik hâle geliyor.

Better i18n, mühendislik ekiplerine i18n borcu biriktirmeyi durdurmak için gereken altyapıyı sunar: AST anahtar taraması, CDN dağıtımlı çeviriler, tür güvenli SDK'lar ve sözlük zorunluluğuyla AI çevirisi. Ücretsiz katman, mevcut borcunuzu denetlemek ve ödemeye başlamak için ihtiyacınız olan her şeyi içeriyor. 10 dakikada başlayın.