wp-content/languages/plugins/ klasörünü açtığınızda her eklenti için iki değil üç dosya görüyorsanız, üçüncüsü WordPress 6.5 ile gelen PHP biçimindeki çeviri dosyasıdır. Uzantısı .l10n.php olur ve .po, .mo dosyalarıyla aynı çevirileri taşır. Fark, WordPress’in onu okuma biçiminde.
Aşağıda bu dosyanın içinde ne olduğunu, WordPress’in onu ne zaman tercih ettiğini, istemiyorsanız nasıl devre dışı bırakacağınızı ve kendi çevirinizden nasıl üreteceğinizi anlatıyoruz.
Üç dosya, üç görev
.po: İnsanın okuyup düzenleyebildiği metin dosyası. Her İngilizce dizenin altında Türkçe karşılığı yazar. Çeviri araçları bu dosyayla çalışır..mo:.podosyasından derlenmiş ikili dosya. WordPress 6.5 öncesinde ekrana gelen çeviriler yalnız buradan okunuyordu..l10n.php: Aynı çevirilerin bir PHP dizisi olarak yazılmış hâli. Dosya bir dizi döndürür; dizide proje bilgileri vemessagesadlı bir alt dizi bulunur. Çekirdek duyurusuna göre girdiler özgün dizeyle anahtarlanır, bağlam bilgisi gettext’teki gibi EOT karakteriyle (U+0004) tekil dizeye eklenir, çoğul biçimler ise boş bayt ("\0") ile ayrılır.
Son ikisi aynı içeriği taşıdığı için birinin güncel, ötekinin eski kalması mümkündür. Sorunların çoğu buradan doğuyor.
Neden PHP dosyası
Çekirdek ekibinden Pascal Birchler’in 27 Şubat 2024 tarihli duyurusu, Performant Translations adlı özellik eklentisinin 6.5 ile çekirdeğe alındığını anlatıyor. Yeni yerelleştirme kütüphanesi .mo dosyalarını da daha hızlı ve daha az bellekle yüklüyor, aynı anda birden fazla dili yükleyebildiği için dil değiştirmeyi de hızlandırıyor. PHP dosyalarının ek avantajı OPcache: sunucudaki PHP’nin derlenmiş kodu bellekte tutan önbelleği, çeviri dosyasını da her istekte yeniden okumadan sunabiliyor. Duyuru bu kazancı rakamla vermiyor, yalnız niteliksel olarak tarif ediyor; bu yüzden burada da yüzde vermiyoruz.
İkisi birden varsa hangisi okunur
Kural tek cümle: bir .mo dosyasının yanında ona karşılık gelen bir .l10n.php dosyası varsa WordPress PHP dosyasını yükler. Yalnız .mo dosyası olan siteler eskisi gibi çalışır; duyuru bunu “progressive enhancement”, yani eskiyi bozmadan eklenen bir iyileştirme olarak tanımlıyor.
WordPress.org’dan inen dil paketleri artık .mo ve .po dosyalarının yanında bir .l10n.php dosyası da içeriyor. translate.wordpress.org’un altındaki GlotPress yazılımı 4.0 sürümüyle bu biçimi destekliyor. Sitenizde bazı eklentiler için PHP dosyası yoksa duyuruya göre bunun basit bir açıklaması olabilir: o eklentinin dil paketi uzun süredir güncellenmemiştir. Paketin ne zaman ve hangi koşulla yeniden üretildiğini dil paketi yazımızda anlattık.
Bir ayrıntı daha: .l10n.php dosyası tek başına, yanında .po ya da .mo olmadan da durabilir. Ama duyuru, güncelleme denetimlerinin hâlâ bu iki dosyayı beklediğini not ediyor ve konuyu 60554 numaralı kayda bağlıyor. Yani yer kazanmak için .po ve .mo dosyalarını silmek, paket güncellemelerinin doğru izlenmesini aksatabilir.
Yaygın tuzak, değişikliğin görünmemesi
Bir çeviri aracıyla .po dosyasını açıp birkaç dizeyi düzelttiniz ve kaydettiniz. Araç .mo dosyasını yeniden derledi ama .l10n.php dosyasına dokunmadı. Ekranda eski çeviri durmaya devam eder, çünkü yukarıdaki kural gereği WordPress hâlâ PHP dosyasını okuyor. Duyuru bu senaryoyu ayrıca yazmıyor; ama okuma kuralından doğrudan çıkan bir sonuç.
Çıkış yolu üç tane:
- PHP dosyasını da yeniden üretmek (aşağıdaki WP-CLI komutu).
- Eski
.l10n.phpdosyasını kaldırmak; WordPress o zaman.modosyasına döner. Ancak bir sonraki paket güncellemesi PHP dosyasını geri getirir ve sizin düzenlemenizi de ezer. - Düzenlemeyi WordPress’in güncellemede dokunmadığı bir klasörde tutmak. Bu klasörlerin hangileri olduğunu çeviri dosyalarının yerini anlatan yazıda sıraladık.
Kalıcı çözüm ise düzeltmeyi translate.wordpress.org’a önermektir; onaylanırsa bir sonraki pakette üç dosya da sizin çevirinizle gelir. Önerilerin neden bazen uzun süre beklediğini onay bekleyen dizeler yazısında ele aldık.
Kendiniz üretmek, wp i18n make-php
Duyuruya göre bu komut WP-CLI 2.10.0 sürümüyle, i18n-command 2.6.0 paketinin parçası olarak geldi. WP-CLI belgesindeki tanımı kısa: PO dosyalarından PHP dosyaları oluşturur. İki girdi alır:
<source>: Tek bir PO dosyasının ya da birden çok PO dosyası içeren bir klasörün yolu.[<destination>]: Oluşan PHP dosyalarının yazılacağı klasör. Verilmezse kaynak klasör kullanılır.
Belgedeki ilk örnek, bulunulan klasördeki tüm PO dosyalarını dönüştürür:
wp i18n make-php .İkinci örnek tek bir PO dosyasından, belirli bir klasöre yazar:
wp i18n make-php example-plugin-de_DE.po languagesBelgede bir de --pretty-print seçeneği geçiyor; çıktıyı okunaklı biçimde yazar, ancak sayfaya göre bu seçenek henüz kararlı bir WP-CLI sürümünün parçası değil. Belgeye göre komut before_wp_load kancasında, yani WordPress’in yükleme süreci başlamadan hemen önce çalışıyor.
WP-CLI kullanamıyorsanız aynı işi PHP içinden yapmak da mümkün. Duyuru, bir .mo dosyasını PHP biçimine çeviren WP_Translation_File sınıfını gösteriyor:
$contents = WP_Translation_File::transform( $mofile, 'php' );
if ( $contents ) {
file_put_contents( $path_to_php_file, $contents );
}Burada $mofile kaynak .mo dosyasının, $path_to_php_file ise yazılacak dosyanın yoludur.
Kapatmak ya da yolu değiştirmek
PHP biçimini hiç kullanmak istemiyorsanız translation_file_format filtresi tercih edilen biçimi belirler. Varsayılan değer php; mo döndürmek PHP dosyası desteğini kapatır:
add_filter(
'translation_file_format',
static function () {
return 'mo';
}
);Bu kodu küçük bir eklentiye ya da mu-plugins klasörüne koymak, tema değişikliğinden etkilenmemesini sağlar. Kapatmanın bir bedeli var: OPcache avantajından vazgeçmiş olursunuz, .mo okuma yine yeni kütüphaneyle hızlı kalır.
Çeviri dosyasının yolunu değiştiren eski kodlar için de bir değişiklik var. Duyuruya göre yıllardır kullanılan load_textdomain_mofile filtresi çalışmaya devam ediyor, ama yalnız .mo yollarını etkiliyor. Yeni load_translation_file filtresi ise iki biçimde de yolu değiştirebiliyor. Kendi çeviri klasörünü bu eski filtreyle devreye sokan bir kod, PHP dosyası bulunan bir sitede beklenen dosyayı yükleyemeyebilir. Çeviri filtrelerinin zamanlamasıyla ilgili başka bir sorun, 6.7’de gelen erken yükleme uyarısıdır.
Geliştiricileri ilgilendiren iki not daha: $l10n küresel değişkeni artık bir MO nesnesi değil, benzer davranan bir WP_Translations nesnesi tutuyor; bu değişkenle ya da MO sınıfıyla doğrudan çalışan kodun gözden geçirilmesi gerekiyor. Ayrıca kurulu dilleri bulmak için yapılan dosya taramaları artık nesne önbelleğinin translations grubunda saklanıyor ve dil paketleri güncellenince temizleniyor.
WordPress.org dışındaki eklentiler
WordPress.org dizinindeki eklentiler PHP çeviri dosyasını otomatik alır; geliştiricinin bir şey yapması gerekmez. Duyurunun yorumlarında Birchler, ticari eklentilerin ise PHP dosyalarını kendilerinin üretmesi gerektiğini yazıyor ve kullanıcıların bunu geliştiricilerine önerebileceğini ekliyor. O zamana kadar Performant Translations eklentisinin ya da WP-CLI’ın üçüncü taraf eklentiler için bu dosyaları üretebileceğini belirtiyor.
Sitemizdeki karneler yalnız WordPress.org dizinindeki eklentileri kapsıyor; ticari eklentilerin çeviri dosyaları bu verinin dışında. Verinin nereden geldiğini ve nasıl hesaplandığını veri ve yöntem sayfasında bulabilirsiniz.