WordPress JSON Çevirisi: Blok Düzenleyici JavaScript Çevirisi

Eklentinizi çevirdiniz. PHP dizeleri yönetici ayarlarında, ön uç şablonlarında, e-posta bildirimlerinde - hepsi yerelleştirilmiş - mükemmel bir şekilde görünüyor. Ardından blok düzenleyiciyi açtığınızda, özel Gutenberg bloğunuzdaki her etiket inatla, alaycı bir şekilde İngilizce kalıyor. "Öğe Ekle" düğmesi, denetçi paneli başlıkları, yer tutucu metin. .mo dosyanız yüklü. Peki neden bu dizeler çevrilmiyor?

Çünkü WordPress 5.0 ve Gutenberg'in gelişiyle birlikte, JavaScript dizeleri .mo dosyanızdan gelmiyor. Bunlar için tamamen ayrı, her betik için WordPress JSON çeviri dosyası gerekiyor - ve bunu oluşturmazsanız, .po dosyanız ne kadar eksiksiz olursa olsun blok düzenleyiciniz İngilizce kalır. Bu, modern WordPress geliştirmesindeki en yaygın ve kafa karıştırıcı yerelleştirme eksikliklerinden biridir. Bu kılavuz, bunun neden olduğunu, JSON çeviri sisteminin nasıl çalıştığını, herkesi şaşırtan MD5-karmalı dosya adlarını ve bunu düzeltmek için tam araç zincirini açıklıyor.

Blok Düzenleyici Dizeleriniz Neden İngilizce Kalıyor?

Kısa cevap: PHP ve JavaScript, WordPress'te tamamen farklı iki çeviri dağıtım sistemi kullanır ve .mo dosyanız yalnızca PHP'yi besler.

İki Çeviri Sistemi, Tek Bir Eklenti

WordPress load_plugin_textdomain()'i çalıştırdığında, derlenmiş .mo dosyanızı PHP belleğine okur. PHP kodunuzdaki her __(), _e() ve _x() çağrısı çevirisini orada arar. Bu, PHP sunucu tarafında işlediği için çalışır - .mo verileri aynı süreçte oradadır.

JavaScript farklıdır. Blok kodunuz, PHP bittikten çok sonra tarayıcıda çalışır. Bir sunucu tarafı .mo dosyasına erişemez. Bunun yerine, @wordpress/i18n paketi - Gettext'in JS karşılığı olan, __(), _x() ve sprintf()'i betiklerinize sunan - çevirilerin, bunlara ihtiyaç duyan belirli betiğe eklenmiş bir JSON yükü olarak teslim edilmesini bekler.

Çevrilmemiş Bir JS Dizesine Ne Olur?

Yani, şöyle dizelere sahip bir blok:

import { __ } from '@wordpress/i18n';

registerBlockType( 'myplugin/feature-box', {
    title: __( 'Feature Box', 'myplugin' ),
    edit: () => {
        return <Button>{ __( 'Add Item', 'myplugin' ) }</Button>;
    },
} );

.mo dosyanızda asla "Özellik Kutusu" veya "Öğe Ekle" bulamaz, çünkü tarayıcılar .mo dosyalarını asla okumaz. Bu dizelerin, tam olarak bu betik tanıtıcısına bağlanmış JSON olarak gelmesi gerekir. Bunu kurmadıysanız, JS __() çağrıları konsolda hiçbir hata olmadan sessizce orijinal İngilizceyi döndürür.

wp_set_script_translations() ile JSON Çevirilerini Bağlama

Betiğiniz ile JSON çevirileri arasındaki köprü tek bir PHP fonksiyonudur: wp_set_script_translations(). "WordPress hangi JSON dosyasının hangi betiğe ait olduğunu nasıl biliyor" sorusunun cevabı şudur: Betiği kaydederek ve ardından metin alanını ve JSON'un bulunduğu klasörü bildirerek siz söylersiniz.

Betiği ve Çeviri Klasörünü Kaydetme

add_action( 'init', function () {
    wp_register_script(
        'myplugin-editor',
        plugins_url( 'build/index.js', __FILE__ ),
        array( 'wp-blocks', 'wp-i18n', 'wp-element' ),
        '1.0.0'
    );

    // Tell WordPress where this script's JSON translations live
    wp_set_script_translations(
        'myplugin-editor',        // the registered script handle
        'myplugin',               // text domain
        plugin_dir_path( __FILE__ ) . 'languages'
    );
} );

Düzenleyici myplugin-editor'ı yüklediğinde, WordPress artık languages/ klasörünüzde bu betik ve geçerli kullanıcının yerel ayarıyla eşleşen bir JSON dosyası arayacağını bilir. Bir tane bulursa, betiğiniz çalışmadan önce çevirileri enjekte eder ve JS __() çağrıları doğru şekilde çözümlenir. Geçtiğiniz tanıtıcı, kayıtlı bir betikle tam olarak eşleşmelidir - uyuşmayan veya eksik bir tanıtıcı, çevirilerin sessizce başarısız olmasının en yaygın ikinci nedenidir.

Kimsenin Beklemediği MD5-Karmalı Dosya Adı

İşte neredeyse herkesi raydan çıkaran detay. WordPress'in aradığı JSON dosyası myplugin-fr_FR.json gibi düzenli bir ada sahip değildir. Betiğin kaynak yolunun MD5 karması ile adlandırılır:

Dosya Adı Desenini Çözümleme

myplugin-fr_FR-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6.json

Desen {textdomain}-{locale}-{md5}.json şeklindedir; burada karma, betik dosyasının kayıtlı olduğu göreli yolun (örneğin build/index.js) MD5'idir. WordPress, doğru betik için doğru JSON'u bulmak üzere bu karmayı çalışma zamanında hesaplar. Dosyanızı elle adlandırırsanız, WordPress onu bulamaz ve sistemin bozuk olduğuna yemin edersiniz, oysa sadece farklı bir dosya adı arıyordur.

Karmayı kendiniz hesaplamazsınız. WP-CLI i18n komutu bunu sizin için yapar, bu da bu dosyaları elle hazırlamak yerine araçları kullanmanızın tam nedenidir. Ancak karmanın var olduğunu anlamak, bir JSON dosyası languages/ içinde olmasına rağmen hala göz ardı edildiğinde size saatler kazandırır - bunun nedeni neredeyse her zaman betik yolunun değişmesi nedeniyle bir dosya adı karma uyuşmazlığıdır.

Tam İş Akışı: make-pot'tan make-json'a

İyi haber şu ki, çevirilerinizi zaten kullandığınız aynı .po dosyalarında tutuyorsunuz. JSON, sonunda oluşturulan türetilmiş bir yapıdır. "JS dizelerini ayrı ayrı mı tutuyorum" sorusunun cevabı hayır - PHP dizelerinizle aynı .pot/.po içinde yaşarlar ve bir ek komut JS dizelerini JSON'a ayırır.

Dört Komutlu İş Akışı

# 1. Extract ALL translatable strings (PHP and JS) into one template
wp i18n make-pot . languages/myplugin.pot

# 2. Translate languages/myplugin-fr_FR.po as usual (Poedit, AI, etc.)

# 3. Compile the .mo for PHP strings (server-side, as always)
wp i18n make-mo languages/

# 4. Generate the MD5-hashed JSON files for JS strings
wp i18n make-json languages/ --no-purge

1. adımın make-pot'u hem .php dosyalarınızı hem de .js/.jsx kaynaklarınızı tarayacak kadar akıllıdır, böylece her yerel ayar için tek bir .po her şeyi tutar. 4. adımın make-json'u, her çevrilmiş .po dosyasını okur, JavaScript dosyalarından gelen girişleri bulur ve her betik için doğru şekilde karmalanmış bir JSON dosyası yazar. --no-purge bayrağı, JS dizelerini .po dosyanızda da tutar, böylece daha sonraki bir make-mo onları kaybetmez - bu olmadan, make-json JS girişlerini .po dosyasından çıkarır, bu da komutları yanlış sırayla çalıştıran kişileri şaşırtır.

Oluşturulan bir JSON dosyası, Jed formatında bir çeviri setine benzer:

{
  "translation-revision-date": "2026-06-12 10:00+0000",
  "generator": "WP-CLI/2.x",
  "domain": "messages",
  "locale_data": {
    "messages": {
      "": { "domain": "messages", "lang": "fr_FR" },
      "Feature Box": [ "Bloc fonctionnalité" ],
      "Add Item": [ "Ajouter un élément" ]
    }
  }
}

WordPress locale_data'yı okur ve betiğiniz çalışmadan önce @wordpress/i18n'e besler. Artık tarayıcıda __( 'Add Item', 'myplugin' ) Ajouter un élément döndürür ve blok düzenleyiciniz nihayet yerelleşir.

Bu, i18next JSON'dan Nasıl Farklıdır?

Her iki sistem de JSON kullanır, her ikisi de JavaScript'i hedefler ve bu yüzeysel benzerlik gerçek bir kafa karışıklığına neden olur. Birbirlerinin yerine kullanılamazlar. WordPress blok düzenleyici JSON'u, @wordpress/i18n tarafından tüketilen, Gettext'ten türetilmiş, MD5-karmalı, betik başına bir yüktür. i18next JSON'u ise react-i18next veya next-intl tarafından tüketilen, kendi {{interpolation}} sözdizimine ve çoğul anahtar kurallarına sahip düz veya iç içe anahtar-değer dosyasıdır.

WordPress dışında saf React veya Next.js ile çalışıyorsanız, React ve Next.js'de i18next JSON'u çevirme konulu yazımızda ele aldığımız i18next yaklaşımını istersiniz. WordPress içinde ise yukarıdaki make-json iş akışını istersiniz. Bunları karıştırmak - örneğin, düz i18next tarzı JSON'u elle yazıp wp_set_script_translations()'ın bunu yüklemesini beklemek - kesinlikle çalışmayacaktır, çünkü WordPress rastgele anahtar-değer çiftlerini değil, karmalı Jed formatını arıyor.

Tek Kaynak, İhtiyacınız Olan Her Format

Tüm bunların kırılganlığı, ortadaki çeviri adımıdır. .po dosyanız hem .mo (PHP) hem de JSON (JavaScript) beslediği için, tek bir hatalı çeviri - bozulmuş bir %s, kırık bir <strong> etiketi, yeniden adlandırılmış bir çoğul form - her iki çıktıyı da aynı anda zehirler. Ve JS dizeleri tarayıcıda eşzamansız olarak yüklendiği için, oradaki yapısal bir hata genellikle zarif bir geri dönüş yerine boş bir etiket veya ciddi bir çökme olarak ortaya çıkar.

Tek Yükleme, PHP ve JavaScript Kapsamında

İşte Gettext yapısını anlayan bir çeviri işlem hattının önem kazandığı yer burasıdır. SimplePoTranslate tek bir kaynak .po veya .pot alır ve tek bir yüklemeden birden çok formatta — .po, .mo, .json, .php ve .xliff — temiz, çevrilmiş çıktı üretir, böylece PHP ve JavaScript katmanlarınız için ayrı araçları bir araya getirmek zorunda kalmazsınız. Sözdizimi Kilitleme özelliği, %s, %1$s, {count} ve satır içi HTML'yi yerinde tutar, bu da blok düzenleyici dizeleri için iki kat önemlidir, çünkü bozuk bir yer tutucu tüm düzenleyici panelini çökertmeye neden olabilir. Tek kaynak, çoklu çıktı modeli hakkında daha derinlemesine bilgiyi Tek dosya girdi, beş format çıktı makalemizde bulabilirsiniz.

WordPress'in beklediği karmalı dosyaları üretmek için hala make-json komutunu çalıştırırsınız - bu adım WordPress'e özgüdür ve derlemenizde kalır. Ancak çevirinin kendisi, JS dizelerinizi bozma olasılığı en yüksek olan kısım, bir bul-değiştir betiği yerine bağlamdan haberdar bir motor tarafından ele alınır.

Sonuç

Blok düzenleyicinizin İngilizce kalmasının nedeni bir hata değil, yapısal bir sorundur: WordPress JSON çevirisi, .mo dosyasından ayrı bir dağıtım sistemidir ve özellikle tarayıcılar sunucu tarafı Gettext verilerini okuyamadığı için oluşturulmuştur. JavaScript dizelerinin wp i18n make-json tarafından oluşturulan ve wp_set_script_translations() ile bağlanan, betik başına, MD5-karmalı JSON'a ihtiyaç duyduğunu anladığınızda, düzeltme mekaniktir. Dizelerinizi tek bir .po dosyasında tutun, PHP için .mo'yu derleyin ve JS için make-json'ı çalıştırın.

Çeviri adımını doğru yaparsanız her iki çıktı da doğru olur. Yanlış yaparsanız, öğleden sonra boş düzenleyici panellerinde hata ayıklamak zorunda kalırsınız.

WordPress JSON ve PHP dizelerinizi tek bir temiz kaynaktan çevirmeye hazır mısınız? SimplePoTranslate'i ücretsiz deneyin — kredi kartı gerekmez. Ücretsiz katman, yer tutucu güvenli Sözdizimi Kilitleme ile gerçek .po ve .pot dosyalarını çevirir, böylece blok düzenleyici dizeleriniz doğru bir şekilde yayınlanır.