Anahtarları veya Yer Tutucuları Bozmadan Bir JSON Dil Dosyası Nasıl Çevrilir

en.json gibi bir JSON dil dosyasını çevirmek için dosyanın tamamını JSON anlayan bir çevirmene verin. Ham metni bir sohbet penceresine veya web çevirmenine yapıştırmak riskli yoldur. JSON bilen bir çevirmen dosyayı okur, yalnızca metin değerlerini çevirir ve aynı anahtarları geri yazar, böylece uygulamanız dosyayı yüklemeye devam edebilir. Kopyala yapıştır bir anahtarı çevirebilir, bir tırnak işaretini değiştirebilir veya bir süslü parantezi düşürebilir. Bunlardan herhangi biri dosyayı bozar.

Anahtarları korumak işin kolay kısmıdır. Sorunların çoğu sonrasında gelir: {nom} olarak geri dönen bir {name} yer tutucusu, other durumunu kaybeden bir ICU çoğulu, diğer metinler gibi çeviriye gönderilen bir URL ve çevirmenin dosyanın kendisinde yaptığı birkaç değişiklik. Bu kılavuz tam olarak bunları ele alıyor.

Tüm bu durumları içeren bir test dosyası oluşturduk ve bir kaynak dosyayı çevirisiyle karşılaştıran ücretsiz bir denetleyici yazdık. Ayrıca test dosyasını, BookTranslator'ın kullandığı JSON ayrıştırma ve yazma kodunun yerel bir kopyasından, model yerine bir işaretleyici ile geçirdik; böylece tam olarak hangi değerlerin gönderildiğini ve dosyanın nasıl geri geldiğini görebilirsiniz.

Hızlı Yanıt: Dosyanın Her Bir Bölümüne Ne Olur

Bu kılavuzun geri kalanı her satırın nereden geldiğini ve ne yapılması gerektiğini gösterir.

Adım 1: Yüklemeden Önce Kaynak Dosyayı Kontrol Edin

Çevirmeyi planladığınız dosyada kontrol aracını çalıştırın. Python 3 dışında hiçbir şeye ihtiyaç duymaz:

python3 check_i18n_json.py en.json

Test dosyamızda şu çıktıyı verdi:

WARN  limits.projectId: 9007199254740993 is above 2^53 and can change in a JavaScript round trip; store IDs as strings
WARN  error.network: a flat key with dots and a nested key resolve to the same dot path; tools that address strings by dot path can mix them up
INFO  (root): 3 keys look like integers; JavaScript sorts those first and in numeric order when it rewrites the object
INFO  source: 17 strings, 2 numbers

İki uyarı ve tamsayı benzeri anahtarlarla ilgili not, test dosyamız çeviriciden geçtiğinde gördüğümüz bir değişiklikle eşleşiyor. Dosyanızda bunların hiçbiri yoksa 3. Adım'a geçebilirsiniz.

Kontrol aracı ayrıca yorumlar veya sondaki virgüller gibi katı JSON olmayan bir dosyayı reddeder, çünkü bir sonraki sorun budur.

Test Dosyamızdan Geri Gelenler

Test, 2 Kasım 2026'da BookTranslator'ın arka ucundaki mevcut JSON işleme karşı çalıştırıldı. Bir modeli çağırmak yerine test, çeviriye gönderilecek her değeri [ZH] ve orijinal metinle değiştirdi. Bu, sonucu öngörülebilir kılar: önünde [ZH] olan her şey gönderildi, olmayanlar gönderilmedi. Her iki çıktı da yayınlandı: çevrilmiş dosya ve iki dilli dosya.

Çevrilen dosya

Her anahtar değişmeden geri geldi ve dosya hâlâ ayrıştırılabiliyordu. Harf içeren değerler gönderildi; bunlara {name}, %s, ICU mesajı, <b> etiketi ve yardım URL'si dahildi. Sürüm dizesi "2.4.1", tire ve boş dize gönderilmedi çünkü hiç harf içermiyorlardı. Sayılar ve boolean değerler olduğu gibi bırakıldı.

Değişen dört şey daha oldu:

1. Bir dize yanlış anahtara gitti. Testimizde dosyamızda "Check your connection." metniyle düz bir "error.network" anahtarı ve ayrıca iç içe "error": { "network": "Network error" } vardı. Çevirmen her dizeyi parçalar arasında nokta bulunan yoluyla tanımlar, bu yüzden her iki dizenin de adresi aynıydı: error.network. Çıktıda her iki anahtar da "Network error" çevirisini tutuyordu. "Check your connection." kaybolmuştu. Bunun için aynı dosyada her iki stilin de bulunması gerekir ki bu nadirdir, ancak sessizce başarısız olur. Denetleyici yüklemeden önce bu konuda uyarır.
2. Tam sayı benzeri anahtarlar yeniden sıralandı. "steps": { "10": ..., "2": ..., "1": ... } çıktısı "1", "2", "10" olarak geldi. JavaScript bir nesneyi yeniden oluştururken tam sayı benzeri anahtarları her zaman önce ve sayısal sırayla listeler. Anahtarlar ve değerler hâlâ eşleşiyor, yani uygulamanız sorunsuz, ancak kaynak dosyayla karşılaştırıldığında fark çıktısı gürültülü olacaktır.
3. Büyük bir ID hassasiyetini kaybetti. 9007199254740993 çıktısı 9007199254740992 olarak geldi. JavaScript sayıları 64 bit kayan nokta olarak saklar ve 2^53 üzerindeki tam sayıların tümü tam olarak temsil edilemez (MDN'de Number.MAX_SAFE_INTEGER). Uzun ID'leri dize olarak saklayın veya dil dosyasının dışında tutun.
4. Biçimlendirme yeniden yazıldı. Çıktı iki boşluk girintisi kullanır ve yeni satırla biter. Kaynağınız sekmeler veya dört boşluk kullanıyorsa fark çıktısında boşluk değişiklikleri bekleyin.

Test dosyamızda yinelenen anahtar yoktu, ancak bunları bilmekte fayda var: JavaScript'in JSON ayrıştırıcısı yinelenen bir anahtar için yalnızca son değeri saklar, bu yüzden önceki metin hiç çevrilmez. Uygulamanız aynı son değeri yükleyeceği için görünürde bir şey bozulmaz, ancak denetleyici yinelenen anahtarları listeler, böylece bunları temizleyebilirsiniz.

İki dilli dosya

İki dilli dosya her orijinal değeri korur ve sonuna _translated eklenmiş bir kardeş anahtar ekler:

"greeting": "Welcome back, {name}!",
"greeting_translated": "[ZH] Welcome back, {name}!",

Bu, inceleme için iyi çalışır çünkü kaynak ve çeviri yan yana durur. Uygulamanızın yükleyebileceği bir dosya değildir çünkü artık her anahtarın bir ikizi vardır. Uygulamanızda çevrilen dosyayı kullanın.

Bir eksik: dizilerin içindeki dizeler _translated kardeşi almaz çünkü dizi öğelerinin eklenecek bir anahtarı yoktur. Testimizde "menu": ["Open", "Save", "Export as EPUB"] iki dilli dosyada İngilizce olarak geri geldi, ancak çevrilen dosyada çevrildi. İki dilli dosyadan inceleme yapıyorsanız çevrilen dosyadaki dizileri kontrol edin.

Yorum içeren dosyalar

Birçok proje dil dosyalarında yorum tutar (JSONC), ki katı JSON buna izin vermez. Çevirmen önce katı JSON'u dener. Bu başarısız olursa yorumları ve sondaki virgülleri kaldırır ve tekrar dener. Yorumları kaldırmak, bir satırda // sonrasındaki her şeyi silmek anlamına gelir ve buna https:// içindeki // de dahildir.

Yorum ve URL içeren dosyamız hiç yüklenmedi; ayrıştırma ilk yorumda başarısız oldu. Yorum içeren ancak herhangi bir değerde // bulunmayan bir dosya sorunsuz yüklendi ve yorumlar çıktıdan çıkarıldı.

Yani: dosyanızda yorum varsa, yüklemeden önce bunları kaldırın veya yorumları içeren bir kopya tutun ve çevirinin bunları içermeyeceğini kabul edin.

Adım 2: Dosyayı Hazırlayın

Bu sorunların çoğunu çeviri yapmadan önce düzeltebilirsiniz:

• Katı JSON yapın. Yorumları ve sondaki virgülleri kaldırın. Derleme aracınız JSONC okuyorsa, yorumlu dosyayı kaynak olarak tutun ve çeviri için temiz bir kopya dışa aktarın.
• Tek bir anahtar stili kullanın. Anahtarları ya iç içe yerleştirin ya da noktalarla düzleştirin, aynı dosyada ikisini birden kullanmayın. i18next kullanıyorsanız, keySeparator seçeneği anahtarlardaki noktaların nasıl okunacağını kontrol eder, bu yüzden herhangi bir şeyi düzleştirmeden önce bu ayarı kontrol edin.
• Metin dışı verileri dışarı taşıyın. ID'ler, URL'ler, özellik bayrakları ve sınırlar yapılandırmaya aittir, dil dosyasına değil. Bir URL kalması gerekiyorsa tutun, ancak çeviriden sonra kontrol etmeyi bekleyin. Çevrilmeyecekler rehberimiz başka nelerin orijinal dilde kalması gerektiğine karar vermeyi kapsar.
• Yer tutucuları her yerde aynı şekilde yazın. {name}, {{name}} ve %s karışımından çok {name} gibi tek bir stil kontrol edilmesi daha kolaydır.

Adım 3: Tüm Dosyayı Çevirin

Temizlenmiş dosyayı BookTranslator'ın belge çevirmenine yükleyin; bu araç, kabul ettiği diğer yerelleştirme ve yapılandırılmış metin biçimleriyle birlikte .json dosyasını da listeler. Fiyat ödeme öncesinde gösterilir. Görev tamamlandığında, geçmiş sayfanız çevrilen dosyayı ve iki dilli dosyayı ayrı indirmeler olarak sunar.

Metnin nasıl çevrildiğine dair iki şey sonucu etkiler:

• Model anahtarlarınızı görmez. Her değer, anahtar adı olmadan numaralı bir segment olarak gönderilir. Eğer "button.open" ve "status.open" ikisi de "Open" diyorsa, model birinin fiil diğerinin sıfat olduğunu bilemez. Kısa ve belirsiz dizeler elle kontrol edilmesi gerekenlerdir.
• Her değer kendi başına çevrilir. İki anahtarı birbirine bağlayan hiçbir şey yoktur, bu yüzden iki yerdeki aynı kelime iki farklı şekilde dönebilir ve iki farklı çeviri gerektiren bir kelime aynı şekilde dönebilir. BookTranslator'ın isteğe bağlı otomatik sözlüğü adları, yerleri ve özel terimleri toplar ve tutarlı tutar, ancak ona kendi sabit çevirilerinizi veremezsiniz. Tam olarak tek bir şekilde çevrilmesi gereken terimler için bir terim listesi tutun ve çeviriden sonra bu dizeleri kontrol edin; sözlük rehberimiz nasıl planlanacağını açıklar.

Satır içi HTML etiketleri çeviriden sonra sayılır ve etiketleri eşleşmeyen bir segment yeniden denenir. Süslü parantez yer tutucuları, %s tarzı yer tutucular ve ICU sözdizimi metnin bir parçası olarak gönderilir ancak aynı şekilde kontrol edilmez. Her çeviri üzerinde 4. Adımı çalıştırın.

Bunun yerine bir sohbet modeli veya yerel model ile çeviri yapmayı tercih ederseniz, yalnızca değerleri gönderin, asla ham dosyayı göndermeyin ve bunları bir betikle anahtara göre geri koyun. Aşağıdaki kontroller her iki durumda da geçerlidir.

4. Adım: Çevrilen Dosyayı Kontrol Edin

Çeviriyi kaynakla karşılaştırın:

python3 check_i18n_json.py en.json fr.json

Neyi yakaladığını göstermek için hata yerleştirilmiş bir Fransızca dosya oluşturduk. Elle yapılmıştır, model çıktısı değildir. 1. Adımdaki aynı kaynak uyarılarından sonra denetleyici şunu yazdırdı:

ERROR app.greeting: placeholders differ; lost ['name'] extra ['nom']
ERROR app.help_url: urls differ; lost ['https://example.com/help'] extra ['https://example.com/aide']
ERROR app.items: ICU message has no 'other' case
ERROR app.legacy: placeholders differ; lost ['%d'] extra []
ERROR limits.maxFiles: type changed from int to str
ERROR limits.projectId: non-text value changed: 9007199254740993 -> 9007199254740992
INFO  menu[1]: identical to source: 'Save'
INFO  compared 20 source values, 1 unchanged strings

Bunların her biri uygulamada bir hata olarak görünür: boş bir ad, bozuk bir bağlantı, çoğul oluşturulurken bir çökme veya ham mesaj, eksik bir bölüm sayısı, metin olarak karşılaştırılan bir sınır. INFO satırı değişmeden dönen dizeleri listeler. Bazıları sorun değildir, marka adları gibi; bir Fransızca menüdeki "Save" değildir.

Denetleyici anahtarları, değer türlerini, metin olmayan değerleri, yer tutucuları ({name}, {{name}}, %s, %1$s, %@), ICU bağımsız değişken adlarını, HTML etiketlerini ve URL'leri karşılaştırır. Çevirinin kendisini yargılamaz.

Çoğul durumların değişmesi beklenir

Bir ICU çoğulu, her çoğul kategorisi için bir mesaj listeler. İngilizce'de one ve other olmak üzere iki kategori vardır, ancak birçok dilde farklı bir küme vardır. items mesajımızın iyi bir Rusça çevirisi normalde one, few, many ve other kullanır, Japonca bir çeviri ise yalnızca other kullanır. Bu nedenle buradaki bir uyumsuzluk her zaman hata değildir.

Kategoriler Unicode CLDR çoğul kurallarından gelir ve other her dilde bulunan kategoridir. Bunlar, Node.js'te CLDR 48 ile Intl.PluralRules tarafından bildirilen asal kategorilerdir:

Fransızca, İspanyolca ve Portekizce many kategorisini yalnızca milyon gibi çok büyük yuvarlak sayılar için kullanır, bu nedenle küçük sayılar için bir mesaj genellikle bu kategoriye ihtiyaç duymaz. Denetleyici, eksik bir other kategorisini hata olarak bildirir ve kategorilerdeki diğer değişiklikleri bu tabloyla karşılaştırmanız için uyarı olarak gösterir. Herhangi bir dil için listeyi kendiniz yazdırabilirsiniz:

node -e 'console.log(new Intl.PluralRules("ru").resolvedOptions().pluralCategories)'

Çevirmene İngilizce durumlar verilir, bu nedenle geri geleni kontrol edin. Rusça veya Arapça bir mesaj hâlâ yalnızca one ve other içeriyorsa, eksik durumları elle ekleyin veya bir çevirmene ekletin.

Ardından uygulamada yükleyin

Denetleyici, dosyanın yüklenmesinin güvenli olduğunu kanıtlar, iyi okunduğunu değil. Uygulamayı yeni dile geçirin ve ekranlara bakın: Almanca veya Fince'de bir düğmeyi taşan uzun kelimeler, Arapça veya İbranice'de sağdan sola metin ve kodunuzun dil dosyasından ayrı olarak biçimlendirdiği tarihler veya sayılar. Çeviri ile yerelleştirme arasındaki fark rehberimiz, kelimelerin yanı sıra pazarlar arasında başka nelerin değiştiğini ele alır.

Yaygın Sorunlar

Çevrilen dosya uygulamama yüklenmiyor. Denetleyiciyi dosya üzerinde çalıştırın. Denetleyici dosyayı ayrıştıramıyorsa, dosya çeviriden sonra düzenlenmiş veya başlangıçta geçersiz olabilir. Ayrıştırıyorsa, anahtarlar veya türlerle ilgili ERROR satırlarını arayın.

Bir dize {count, plural, ...} gibi ham bir ICU mesajı olarak görünüyor. ICU sözdizimi çeviride bozulmuş, genellikle eksik bir süslü parantez veya eksik bir other durumu. Yapıyı kaynaktan kopyalayın ve yalnızca her durumun içindeki kelimeleri çevirin.

Dosyam YAML, bir .po dosyası veya Markdown. BookTranslator bunları da kabul eder, ancak her biçimin kendi kuralları vardır. Belgeler için Markdown çeviri rehberimize, web sayfaları için HTML dosyası rehberine bakın.

Yalnızca yeni anahtarları çevirebilir miyim? Tek bir yükleme içinde hayır; dosyanın tamamı çevrilir. Yeni anahtarları ayrı bir dosyaya koyun, çevirin ve sonucu anahtara göre birleştirin. Denetleyici, birleştirilmiş dosyanın her anahtarı içerdiğini doğrular.

Anahtarları çevirmeli miyim? Hayır. Anahtarlar, kodunuzun aradığı tanımlayıcılardır. Yalnızca değerler, insanların okuması için metindir.