WordPress 6.7’deki erken çeviri yükleme uyarısı ne anlatır

WordPress 6.7 sürümünden sonra hata günlüğünde “Function _load_textdomain_just_in_time was called incorrectly” ile başlayan bir satır görüyorsanız, sitenizdeki eklentilerden biri çevirilerini WordPress’in beklediğinden önce istiyor demektir. Uyarı sitenizi bozmaz; bir geliştirici hatasını görünür kılar. Ama aynı hata, bazı durumlarda bir eklentinin Türkçe paketi kurulu olduğu hâlde ekranda İngilizce kalmasının da nedeni olabilir.

Bu yazı uyarının hangi koşulda doğduğunu, geliştiricinin onu nasıl kapattığını ve kodla uğraşmayan bir site sahibinin ne yapabileceğini anlatıyor.

Uyarı tam olarak neyi bildiriyor

Çekirdek ekibinden Pascal Birchler’in 21 Ekim 2024 tarihli duyurusuna göre WordPress 6.7, çeviriler çok erken yüklendiğinde geliştiriciyi uyaran bir bildirim ekledi. “Çok erken” burada somut bir ana karşılık geliyor: after_setup_theme ya da init kancası çalışmadan önce. Kanca, WordPress’in açılış sırasında belli bir noktaya geldiğini haber verdiği ve eklentilerin kendi kodunu bağladığı yerdir. Duyurunun yorumlarında aktarılan mesaj, sorunlu metin alanının adını verip çevirilerin init eylemi ya da daha sonrası yüklenmesi gerektiğini söylüyor.

Neden bu sınır çizildi? Duyuruya göre çeviriyi erken yüklemek WordPress’i o anki kullanıcıyı da erkenden belirlemeye zorluyor ve bunu başka eklentilere araya girme fırsatı tanımadan yapıyor. Ayrıca çeviri çağrılarının filtrelenmesini engelliyor; dil değiştirme ya da çeviri dosyasının yerini değiştirme gibi işler bu filtrelere dayanıyor.

Uyarının adındaki “just in time” ifadesi, WordPress 4.6’da gelen bir mekanizmayı anlatır. Bir metin alanına ait ilk çeviri istendiği anda WordPress dosyayı kendisi bulur ve yükler. Eklentinin ayrıca bir yükleme fonksiyonu çağırmasına gerek kalmaz. Uyarı da tam bu mekanizma vaktinden önce tetiklendiğinde çıkıyor.

Uyarıyı doğuran üç tipik kod

Duyuru iki örnek veriyor, üçüncüsü bunların doğal bir türevi.

1. Sürüm numarası için get_plugin_data() çağırmak

Birçok eklenti kendi sürüm numarasını ana dosyanın başlığından okur. get_plugin_data() fonksiyonu varsayılan olarak başlıktaki tüm bilgileri, yani eklenti adını ve açıklamasını da çevirir. Bu çağrı ana dosyada, init gelmeden yapılırsa çeviri erken istenmiş olur. Duyurunun önerdiği düzeltme üçüncü parametreyi, yani $translate değerini false yapmaktır:

$veri = get_plugin_data( __FILE__, false, false );
$surum = $veri['Version'];

Duyurunun yorumlarında da bu çağrının uyarıyı en sık doğuran kod olduğu belirtiliyor.

2. Ana dosyada erken __() çağrısı

__() WordPress’in çeviri fonksiyonudur; bir İngilizce dizeyi alır, varsa çevirisini döndürür. Eklentinin ana dosyasında, herhangi bir kancaya bağlanmadan doğrudan çalışan bir __() çağrısı, eklenti yüklenir yüklenmez çeviri ister. O sırada init henüz gelmemiştir.

3. Kurucusunda çeviri olan bir sınıfı hemen oluşturmak

Duyurudaki ikinci örnek budur. Eklenti ana dosyada bir sınıfı oluşturur, sınıfın kurucu fonksiyonu da bir menü başlığı ya da ayar etiketi için __() çağırır. Kod düzgün görünür, ama sınıf init öncesinde oluştuğu için çeviri yine erken istenir.

Geliştiricinin düzeltmesi

Önerilen yol, çeviri çağrılarını ve sınıf oluşturmayı init ya da daha sonraki bir kancaya ertelemek; ya da çeviri çağrısını gerçekten gerekli olduğu ana kadar bekletmek. Kabaca şöyle:

add_action( 'init', function () {
    new Eklenti_Ayarlari();
} );

Uyarının hangi koddan geldiğini bulmak zor olabilir, çünkü mesaj yalnızca metin alanını söyler. Duyuru bunun için doing_it_wrong_run kancasına bağlanıp fonksiyon adı _load_textdomain_just_in_time olduğunda debug_print_backtrace() çağırmayı öneriyor. Bu, uyarıya giden çağrı zincirini dosya ve satır olarak döker. Duyuruda Query Monitor eklentisi de bu iş için yardımcı bir araç olarak anılıyor.

load_plugin_textdomain artık ne yapıyor

Eski eklentilerin çoğunda load_plugin_textdomain() çağrısı bulunur. Eklenti el kitabındaki örnek bu fonksiyonu init kancasına bağlayarak çağırıyor. WordPress 6.7 ile bu fonksiyonun ve tema karşılığı load_theme_textdomain() fonksiyonunun davranışı değişti: asıl yüklemeyi artık kendileri yapmıyor, 4.6’dan beri var olan anında yükleme mantığına bırakıyorlar.

Bunun pratik bir sonucu var. Duyuruya göre bu fonksiyonları erken çağırmak 6.7’de tek başına hiçbir şey yapmıyor; uyarı yalnızca çeviri fonksiyonları erken çalıştığında çıkıyor. Yani günlükte bu satırı görüyorsanız sorun büyük ihtimalle bir __() ya da get_plugin_data() çağrısında, yükleme fonksiyonunda değil.

WordPress.org’da barındırılan eklentiler için bu çağrı zaten gereksiz. El kitabına göre WordPress 4.6 sürümünden itibaren öncelik translate.wordpress.org’daki çevirilerde; el kitabı çağrıyı eklemek istemeyen geliştiriciden readme.txt dosyasındaki Requires at least: alanını 4.6 ya da üzeri yapmasını istiyor. WordPress.org dışında dağıtılan ya da eski sürümleri desteklemeye devam eden eklentiler ise duyuruya göre çağrıyı init veya sonrasına taşımalı.

Site sahibi olarak bu uyarıyı neden görüyorsunuz

Uyarı ziyaretçinize görünmez, çünkü bir geliştirici bildirimidir. Onu görmenizin nedeni neredeyse her zaman wp-config.php dosyasında hata ayıklama ayarlarının açık olmasıdır.

WordPress’in hata ayıklama belgesine göre:

• WP_DEBUG varsayılan olarak kapalıdır. Açıldığında tüm PHP hataları, bildirimleri ve uyarıları gösterilir.
• WP_DEBUG_LOG, WP_DEBUG açıkken bu iletileri ayrıca içerik klasöründeki debug.log dosyasına, çoğunlukla wp-content/debug.log yoluna yazar.
• WP_DEBUG_DISPLAY varsayılan olarak açıktır ve iletileri oluştukları anda sayfada gösterir. false yapıldığında hepsi gizlenir.

Belgedeki örnek yapılandırma günlüğü açıp ekran gösterimini kapatır:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

Uyarıyı yönetim panelinin tepesinde ya da sayfaların üstünde görüyorsanız WP_DEBUG_DISPLAY açık kalmış demektir. Aynı belge, hata ayıklama araçlarının canlı sitelerde kullanılmasını önermiyor; bunları yerel ya da hazırlık (staging) ortamı için tarif ediyor ve canlı sitede değişiklik yapmadan önce yedek almayı hatırlatıyor. Bir de küçük ama sık rastlanan tuzak var: değeri tırnak içinde 'false' diye yazmak bir metin üretir ve WordPress bunu açık sayar.

Ne yapabilirsiniz

1. Hangi eklenti olduğunu bulun. Mesajdaki metin alanı adı çoğu zaman eklentinin kısa adıdır. WordPress.org’daki eklentilerde metin alanı el kitabının kuralı gereği eklentinin adresindeki kısa adla aynıdır.
2. Eklentiyi güncelleyin. Geliştirici sorunu yeni bir sürümde gidermiş olabilir. Güncel sürümde de uyarı sürüyorsa sorun hâlâ açık demektir.
3. Geliştiriciye bildirin. WordPress.org’daki eklentiler için destek forumu doğru yer. Mesajın tam metnini ve mümkünse doing_it_wrong_run ile alınmış çağrı zincirini eklemek, geliştiricinin sorunu bulmasını hızlandırır.
4. Uyarıyı susturmak için çekirdek dosyalarına dokunmayın. Gereken tek ayar canlı sitede WP_DEBUG_DISPLAY değerini kapalı tutmaktır.

Çeviri neden İngilizce kalabiliyor

Uyarı çoğu durumda yalnızca bir uyarı olarak kalır. Ama duyurunun anlattığı iki yan etki, Türkçe paketi kurulu bir eklentinin ekranda kısmen İngilizce görünmesini açıklayabilir.

Birincisi, erken yükleme çeviri filtrelerini devre dışı bırakır. Bir çeviri eklentisi kendi klasöründeki düzeltilmiş dosyayı devreye sokmak için çeviri dosyasının yerini değiştiren filtrelere dayanır. Eklenti çeviriyi bu filtreler kurulmadan isterse sizin özel dosyanız hiç okunmayabilir. Dosyaların nerede durduğunu ve hangisinin önce okunduğunu çeviri dosyalarının yerini anlatan yazıda ayrıntılı ele aldık.

İkincisi, dil değiştirme de aynı filtrelere bağlıdır. Yönetim panelini kendi profil dilinizde kullanıyorsanız ya da çok dilli bir eklenti sayfa başına dil seçiyorsa, erken istenen dizeler bu seçim yapılmadan yüklenmiş olabilir.

Bu iki durumu, paketin kendisinin eksik olmasından ayırmak gerekir. Eklentinin Türkçe paketinde dize zaten yoksa uyarıyı düzeltmek bir şey değiştirmez. Paketin durumunu ve eksik dizelerin neden oluştuğunu yarı Türkçe kalan eklentileri inceleyen yazı ele alıyor. Çevirisi yüzde 90 eşiğine yaklaşmış ama henüz paketi çıkmamış eklentileri ise eşiğe yakın listesinde bulabilirsiniz; bu eklentilerde İngilizce görünmenin sebebi kod değil, eksik çeviridir.

Kısa bir ayrım tablosu

Son satırdaki durumda yapılacak iş koddan çok çeviriyle ilgili. Eksik dizeleri translate.wordpress.org’da nasıl önereceğinizi katkı rehberinde adım adım anlattık.