React ve Next.js'te i18next JSON Dosyaları Nasıl Çevrilir (2026)

Gelecek Cuma'ya kadar 12 dilde yayınlanması gereken bir React uygulamasını yeni bitirdiniz. Yerel ayar dosyalarınız public/locales/en/common.json içinde yer alıyor, her yerel ayar için 340 anahtarınız var ve dizelerinizin içindeki jetonlar iç içe nesnelerin arasına dağılmış {{userName}} ve {{count}} gibi görünüyor. JSON'u ChatGPT'ye yapıştırıyorsunuz ve karşılığında {{ nombreUsuario }}, fazladan boşluklar ve çoğullaştırma anahtarlarının yarısı yeniden adlandırılmış olarak geri dönüyor. Uygulamanız derleme sırasında çöküyor.

i18next JSON çevirisini otomatikleştirmeyi denediyseniz, bu acıyı bilirsiniz. JSON formatı esnektir ve çoğu çeviri aracının onu bozmasının nedeni de tam olarak budur. Asıl sorun dil modelinin kalitesi değil; tüketici sınıfı yapay zeka araçlarının i18next'in yapısal kurallarını anlamamasıdır.

Bu rehber, i18next JSON'u diğer yerel ayar formatlarından neyin farklı kıldığını, basit çeviri yaklaşımlarının React ve Next.js uygulamalarını neden bozduğunu ve her anahtarı manuel olarak incelemeye gerek kalmadan düzinelerce yerel ayar arasında çeviriyi güvenli bir şekilde nasıl otomatikleştireceğinizi açıklıyor.

i18next JSON Nedir ve Çevirisi Neden Zordur?

i18next, JavaScript ekosistemindeki en yaygın kullanılan i18n kütüphanesidir. React (react-i18next), Next.js (next-i18next, App Router next-intl), Vue ve Node arka uç hizmetlerine güç verir. Çevrilebilir dizeleri, her yerel ayar için bir tane olmak üzere düz veya iç içe JSON dosyalarında saklar.

Tipik bir dosya şuna benzer:

{
  "welcome": "Welcome, {{userName}}!",
  "cart": {
    "empty": "Your cart is empty",
    "items_one": "{{count}} item in your cart",
    "items_other": "{{count}} items in your cart"
  },
  "errors": {
    "network": "Network error. <strong>Please retry</strong>."
  }
}

Bu basit görünse de, üç şey onu genel amaçlı yapay zeka ile çevirmek için tehlikeli kılar.

Enterpolasyon Jetonları Yapısaldır, Metin Değil

{{userName}} dizisi bir kelime değildir; çalışma zamanının verilerle değiştirdiği bir yer tutucudur. Bir boşluk ({{ userName }}) ekleyin, yeniden adlandırın veya iç tanımlayıcıyı çevirin; çalışma zamanı sessizce başarısız olur veya hata verir. Bazı çevirmenler yardımcı bir şekilde İspanyolcada {{count}} öğesini {{conteo}} olarak dönüştürür. Uygulamanız artık var olmayan bir değişkeni enterpole etmeye çalışır ve ham yer tutucuyu kullanıcınıza görüntüler.

Çoğullaştırma Anahtarları Sihirli Son Ektir

i18next, çoğulları _zero, _one, _two, _few, _many, _other son ekleriyle algılar. Bunlar rastgele dizeler değildir; hedef yerel ayar için CLDR çoğul kategorileriyle eşleşmelidir. İngilizce yalnızca _one ve _other kullanır. Rusça, Arapça ve Lehçe altıya kadar kategori kullanır. Çevirmeniniz _other öğesini bırakır veya yeniden adlandırırsa, geri dönüş zinciri bozulur.

İç İçe Anahtarlar Bozulmadan Kalmalıdır

Düz anahtar-değer çiftleri olan Gettext .po dosyalarının aksine, i18next dosyaları keyfi olarak iç içe geçebilir. Tembel bir çevirmen yapıyı düzleştirebilir, anahtar adlarını çevrilmiş metinle eşleşecek şekilde değiştirebilir veya nesneleri yeniden sıralayabilir. Kodunuzdaki t('cart.items_other') çağrınız artık çözümlenemez.

Geliştiricilerin İlk Denemeye Çalıştığı Kötü Çözümler

Her ekip, gerçek bir çözüme yatırım yapmadan önce aynı üç aşamalı başarısızlık döngüsünden geçer.

Birinci Aşama: ChatGPT'ye Yapıştırma

ChatGPT'ye 200 anahtarı kopyalar, "bu JSON'u İspanyolcaya çevir" diye sorar ve sonucu geri yapıştırırsınız. 180 anahtar için çalışır. Yirmisinde {{...}} içine boşluklar eklenmiş, üçünde çoğul son ekleri yeniden yazılmış ve bir <strong> etiketi <fuerte> olarak çevrilmiş. Derlemeniz ya başarısız olur ya da bozuk dizeleri sessizce üretime gönderir.

İkinci Aşama: Google Translate API

Google Translate REST API'sini bağlar, JSON'unuz üzerinde yineler ve her değeri gönderirsiniz. Hız harika. Kalite değil. Google'ın API'si her dizeyi ayrı ayrı ele alır - uygulamanız hakkında bağlam yok, {{count}} öğesinin bir yer tutucu olduğu anlaşılmıyor, cart.empty anahtarının cart.items_one öğesinden farklı olduğu fark edilmiyor. Her anahtar için hala insan incelemesine ihtiyacınız var.

Üçüncü Aşama: Ticari TMS Platformları

Bir çeviri yönetim sistemine kaydolursunuz. Kelime başına ücret alırlar, GitHub entegrasyonları gerektirirler ve sizi aylık koltuklara bağlarlar. Bir yan proje veya bağımsız bir uygulama için ekonomik denge hızla bozulur - ve motorları özellikle i18next formatını ayrıştırmazsa yine aynı yer tutucu bozulma sorunlarıyla karşılaşırsınız.

Aynı hata modları Gettext iş akışlarında da ortaya çıkar. Kod değişkenlerini bozmadan .po dosyaları nasıl çevrilir hakkındaki rehberimiz, WordPress ve diğer Gettext tabanlı yığınlar için benzer sorunu ele almaktadır.

Güvenli Yaklaşım: Sözdizim Duyarlı Çeviri

i18next JSON'u büyük ölçekte çevirmenin tek güvenilir yolu, önce formatı ayrıştıran, sözdizimini kilitleyen ve yalnızca çevrilebilir metni yapay zekaya gönderen bir araç kullanmaktır.

Sözdizim duyarlı işlem arka planda şunları yapar:

1. JSON'u soyut bir ağaca ayrıştırır, anahtar yollarını ve iç içe geçmeyi korur.
2. Enterpolasyon belirteçlerini ({{name}}, {{count, number}}, {{date, datetime}}) tanımlar ve bunları yer tutucu kimlikleriyle değiştirir.
3. Trans bileşenlerinin içindeki HTML etiketlerini (<0>, <strong>, <br/>) tanımlar ve kilitler.
4. Çoğul anahtarları son eke göre algılar ve hedef yerel ayar için CLDR kurallarıyla eşler.
5. Yalnızca temizlenmiş metni, anahtar yolu hakkında bağlamla birlikte LLM'ye gönderir.
6. Orijinal belirteçleri ve etiketleri tam konumlarına geri ekler.
7. Çıktıyı doğrular - herhangi bir yer tutucu eksik veya bozuksa, kaynağa geri döner.

Bu, bulut tabanlı PO çevirisini güvenli kılan aynı ilkedir. Temel mimariyi merak ediyorsanız, Yapay zeka çeviri kalitesi karşılaştırmamız farklı LLM'lerin bu kısıtlamaları nasıl ele aldığını ayrıntılarıyla açıklar.

Adım Adım: SimplePoTranslate ile i18next JSON Çevirisi

SimplePoTranslate, Pro ve Lifetime planlarında i18next JSON'u doğal olarak destekler. Ücretsiz katman şu anda .po ve .pot dosyalarını kapsar - JSON'a erişmek için yükseltme yapın veya deneme sürümünü kullanın.

1. Kaynak Dosyanızı Hazırlayın

İngilizce (veya kaynak yerel ayar) dosyanızı ana dosya olarak kullanın. Geçerli bir JSON olduğundan ve uygulamanızın kullandığı tüm anahtarları içerdiğinden emin olun. Yaygın bir hata, eski veya kullanılmayan anahtarları bırakmaktır; bu, asla işlemeyeceğiniz dizeler için çeviri kotanızı tüketir.

# From your project root
cp public/locales/en/common.json ~/Desktop/common.json

2. SimplePoTranslate'e Yükleyin

Kontrol panelinize giriş yapın, Yeni Çeviri'ye tıklayın ve common.json dosyasını yükleyin. Platform, i18next formatını otomatik olarak algılar. Desteklenen 41 yerel ayardan hedef dilinizi seçin, bir ton (profesyonel, gündelik, pazarlama) belirleyin ve gönderin.

3. Motoru Çalıştırın

Arka planda, dosya ayrıştırılır, güvenli gruplara ayrılır ve paralel olarak çevrilir. Enterpolasyon belirteçleri kilitlenir. Çoğul son ekler korunur ve hedef yerel ayarın CLDR kurallarıyla eşlenir. Trans bileşenlerinin içindeki HTML bozulmadan kalır.

4. ZIP Dosyasını İndirin

Çevrilmiş JSON ile birlikte alternatif formatları (.php PHP uygulamaları için, .po araçlar arası uyumluluk için) içeren bir ZIP dosyası alırsınız. JSON'u public/locales/es/common.json içine bırakın ve yeniden dağıtın.

unzip common_es.zip
mv common.json public/locales/es/common.json
npm run build

5. Tekrarla veya Toplu İşlem Yap

Tüm 12 hedef yerel ayar için 12 iş gönderin. Pro plan kotaları düzinelerce tipik SaaS uygulamasını kapsar. Birden fazla ad alanı dosyası olan monorepo'lar için, her birini ayrı ayrı yükleyin veya bunları sırayla toplu olarak işleyin.

Çevirileri Uygulamanıza Geri Entegre Etme

JSON dosyalarını çevirdikten sonra, entegrasyon kolay kısımdır. Birkaç püf nokta:

• Çoğul kategorileri doğrulayın. Her yerel ayar için hızlı bir duman testi yapın: count={0}, count={1}, count={5} ile bir bileşeni işleyin ve üçünün de doğru dizeyi ürettiğini onaylayın.
• RTL yerel ayarlarını kontrol edin. Arapça, İbranice veya Farsça'ya çeviri yaptıysanız, kullanıcı arayüzünüzün RTL'ye duyarlı CSS'e ihtiyacı vardır. WordPress RTL çeviri rehberimiz React uygulamalarına da uygulanan CSS desenlerini kapsar.
• Bir geri dönüş zinciri kurun. Bir anahtar eksikse i18next'i İngilizce'ye geri dönecek şekilde yapılandırın, böylece dağıtım ortası durumlar kullanıcıları çökertmez.
• Kaynak dosyanızı CI'da kilitleyin. en/common.json dosyasının diğer yerel ayarları yeniden oluşturmadan değiştiği PR'ları reddeden bir kontrol ekleyin. Çeviri kayması, üretim i18n hatalarının en büyük tek nedenidir.

React, Next.js ve sunucu tarafında dağıtım yapan ekipler için, her formatı tek bir kaynaktan üretmek büyük bir kazançtır. Bir giriş dosyası, beş çıkış formatı hakkındaki yazımız, uzun vadeli bakım için çok formatlı çıktının neden önemli olduğunu açıklar.

JSON Yeterli Olmadığında: Karmaşık Durumları Yönetme

Birkaç uç durum ekstra dikkat gerektirir.

ICU MessageFormat

Projeniz ICU sözdizimi ({count, plural, one {1 item} other {# items}}) kullanıyorsa, i18next bunu enterpolasyon olarak kabul eder ancak yapısı daha karmaşıktır. Çeviri aracınızın ICU parametrelerini tanıdığından ve one, other gibi kategori adlarını veya plural, number, date gibi format tanımlayıcılarını çevirmediğinden emin olun.

React Düğümlü Trans Bileşeni

<Trans>, çevrilmiş dizelerin içinde React bileşenlerini dizinle (<0>, <1>) anahtarlanmış olarak işler. Çevirmen, tam etiket sırasını korumalıdır. SimplePoTranslate'in sözdizimi kilidi bunu halleder, ancak farklı bir araç kullanıyorsanız, dağıtımdan önce doğrulayın.

Ad Alanı Dosyaları

Büyük uygulamalar yerel ayarları ad alanlarına ayırır: common.json, dashboard.json, checkout.json. Her dosyayı bağımsız olarak çevirin - birleştirmeyin. Her ad alanının anahtar yolları kapsamlı kaldığında bağlam kalitesi daha yüksektir.

Hepsini Bir Araya Getirme

Bir React veya Next.js uygulaması için i18next JSON'u çevirmek, en iyi yapay zeka modelini seçmekle ilgili değildir. Formatın yapısal kurallarına saygı duymakla ilgilidir: enterpolasyonlar, çoğul son ekler, iç içe anahtarlar ve HTML etiketleri gidiş dönüşe dayanmalıdır. Tüketici yapay zeka araçları JSON'u yapılandırılmamış metin olarak ele alır. Sözdizim duyarlı araçlar onu yapılandırılmış veri olarak ayrıştırır ve yalnızca çevrilebilir yüzeylere dokunur.

Çok dilli bir uygulama yayınlıyorsanız ve JSON'u sohbet arayüzlerine kopyala-yapıştır yapıyorsanız, maliyetini zaten biliyorsunuzdur: yerel ayar başına saatler süren manuel inceleme, rastgele üretim hataları ve giderek artan bozuk çoğul form yığını. Formata duyarlı bir işlem hattı, bu hata modlarının her birini ortadan kaldırır.

i18next JSON dosyalarınızı güvenli bir şekilde çevirmeye hazır mısınız? SimplePoTranslate'i ücretsiz deneyin - kredi kartı gerekmez. Bir kez yükleyin, 41 dilde yayınlayın.