Tema güncellenince Türkçe çeviri neden kaybolur, .po ve .mo dosyaları nereye konur

Tema klasörünün içine koyduğunuz tr_TR.mo dosyası, tema güncellendiğinde temanın geri kalanıyla birlikte yenisiyle değiştirilir. WordPress bir temayı güncellerken klasörü paketten gelen sürümle yeniler, paketin içinde sizin dosyanız olmadığı için çeviri de gider. Kalıcı bir yerel çeviri için doğru yer wp-content/languages/themes/ klasörüdür. Ancak bu klasörün de kendi kuralları var ve tema için Türkçe dil paketi varsa orada da sürpriz yaşayabilirsiniz. Aşağıda iki konumun farkını, dosya adlarını, yükleme sırasını ve WordPress 6.5 ile gelen .l10n.php dosyalarının etkisini resmî belgelere dayanarak anlatıyoruz.

Üç dosya türü, üç görev

Bir çeviri dosyası seti genellikle şunlardan oluşur.

• .po (Portable Object). İnsanın okuyabildiği metin dosyasıdır. Her İngilizce dizenin (msgid) karşısında Türkçesi (msgstr) yazar. Düzenleme bu dosyada yapılır.
• .mo (Machine Object). .po dosyasının derlenmiş, makinenin okuduğu hâlidir. Theme Handbook’un ifadesiyle WordPress’in fiilen kullandığı dosya budur.
• .l10n.php. WordPress 6.5 ile gelen, çevirileri bir PHP dizisi olarak tutan biçimdir. Aşağıda ayrıca ele alıyoruz.

.po dosyasını düzenleyip .mo dosyasını yeniden üretmezseniz sitede hiçbir şey değişmez. Panelden çeviri düzenlemeye yarayan eklentiler bu derleme adımını sizin yerinize yapar ve bazıları dosyanın nereye kaydedileceğini de sorar. Bu sorunun cevabı, çevirinin güncellemeden sağ çıkıp çıkmayacağını belirler.

WordPress çeviriyi iki yerde arar

Theme Handbook, sitenin dili için WordPress’in iki konuma baktığını yazar.

Dosya adındaki fark sık yapılan bir hatanın kaynağıdır. Tema klasöründe dosyanın adı yalnızca yerel koddan oluşur (tr_TR.mo). Ortak dil klasöründe ise başına temanın metin alanı (text domain) gelir, örneğin astra-tr_TR.mo. Metin alanı, temanın çevrilebilir dizelerini öbür tema ve eklentilerinkinden ayıran kimliktir ve WordPress.org’daki temalarda genellikle tema klasörünün adıyla aynıdır. Emin değilseniz temanın style.css başlığındaki Text Domain: satırına bakın. Tema klasöründeki alt klasörün adı da sabit değildir. style.css içindeki Domain Path: başlığı bu yolu belirtir, başlık yoksa varsayılan /languages kabul edilir.

Tema klasörüne astra-tr_TR.mo adıyla konmuş bir dosya ya da ortak klasöre tr_TR.mo adıyla konmuş bir dosya yüklenmez. Çevirinin “hiç çalışmadığı” şikâyetlerinin bir kısmı bu ad karışıklığından gelir.

Neden tema klasörünün güncellemede yenilendiğini anlamak için Theme Handbook’un alt temalar sayfasındaki uyarı yeterli. Ana temanın dosyalarında yaptığınız değişiklik, tema bir sonraki güncellemeyi aldığında kaybolur. Çeviri dosyası da bu kuralın dışında değildir.

Hangisi önce yüklenir

İki konumda da dosya varsa ortak dil klasöründeki kazanır. load_theme_textdomain() sayfasının değişiklik kaydı, fonksiyonun 4.6 sürümünden beri .mo dosyasını önce dil klasöründen yüklemeye çalıştığını yazar. Güncel kodda bu sıra WP_Textdomain_Registry sınıfında görülür. get_paths_for_domain() önce wp-content/languages/plugins, ardından wp-content/languages/themes yolunu listeler. Temanın kendi klasörü (temanın load_theme_textdomain() ile kaydettiği özel yol) listenin en sonuna eklenir.

Bunun pratik sonucu şudur. Temanın translate.wordpress.org’da oluşmuş bir Türkçe dil paketi varsa WordPress bu paketi wp-content/languages/themes/ klasörüne indirir ve tema klasörüne koyduğunuz tr_TR.mo hiç okunmaz. Yani tema klasörüne çeviri koymak, güncellemeye kadar bile çalışmayabilir.

WordPress 6.7 ile gelen tembel yükleme

WordPress 6.7’den itibaren load_theme_textdomain() çeviriyi çağrıldığı anda yüklemez, işi “tam zamanında” (just-in-time) yükleme mekanizmasına devreder. Çeviri, temanın ilk dizesi ekrana basılacağı zaman okunur. Make WordPress Core’un 6.7 notu ayrıca çevirilerin çok erken, yani after_setup_theme ya da init kancalarından önce yüklenmeye çalışıldığında geliştiriciye uyarı verildiğini belirtir. Bu uyarı, hata ayıklama kaydınızda _load_textdomain_just_in_time adıyla görünür ve çevirinin yüklenmediğini değil, temanın çeviriyi erken istediğini anlatır.

Tam zamanında yükleme sırasında dosya adı şöyle kurulur. Bulunan yol temanın kendi klasörüyse ad tr_TR.mo, başka bir yerse <textdomain>-tr_TR.mo olur. Yukarıdaki tablodaki ad kuralının kodda karşılığı budur.

Ortak dil klasörü güvenli mi

Tema güncellemesi açısından evet. wp-content/languages/themes/ temanın klasörü olmadığı için tema güncellendiğinde yerinde kalır.

Dil paketi güncellemesi açısından duruma göre değişir. Language_Pack_Upgrader sınıfının kaynağında tema dil paketlerinin hedefi WP_LANG_DIR altındaki /themes klasörüdür. Güncellemeler ekranından çevirileri güncellediğinizde ya da otomatik çeviri güncellemesi çalıştığında paket bu klasöre aynı dosya adlarıyla açılır. Elle koyduğunuz tema-tr_TR.mo ile paket aynı adı taşıdığı için sizin dosyanızın üzerine yazılır.

Bu yüzden iki durumu ayırmak gerekir.

1. Temanın Türkçe dil paketi yok. Bir dil paketi ancak çeviri %90’a ulaştığında oluşturulur, ayrıntısını dil paketi %90 kuralı yazısında anlattık. Paket hiç oluşmamışsa wp-content/languages/themes/<textdomain>-tr_TR.mo dosyanızın üzerine yazacak bir şey yoktur, çeviri hem tema hem çekirdek güncellemelerinden sağ çıkar.
2. Temanın Türkçe dil paketi var. Bu durumda ortak klasöre koyduğunuz dosya bir sonraki çeviri güncellemesinde gider. Ya düzeltmenizi translate.wordpress.org’a öneri olarak gönderirsiniz ya da dosyanızı ayrı bir klasörde tutup WordPress’e onu okutursunuz.

Bir temanın Türkçe paketinin olup olmadığını tema listemizdeki karnelerde görebilirsiniz. Paketin varlığını gösteren bilgi translate.wordpress.org verisinden gelir, yöntemini veri ve yöntem sayfasında açıkladık.

WordPress 6.5 ve .l10n.php dosyaları

WordPress 6.5 çeviri yüklemeyi hızlandırmak için yeni bir biçim getirdi. Make WordPress Core’daki duyuruya göre bir .mo dosyasının yanında aynı adlı bir .l10n.php dosyası varsa WordPress .mo yerine onu yükler. Duyuruya göre PHP dosyası daha hızlı yüklenir ve daha az bellek kullanır. Yalnızca .mo dosyası varsa çeviriler eskisi gibi yüklenir.

Bunun yerel çeviri yapan biri için önemli bir yan etkisi var. wp-content/languages/themes/ klasöründe dil paketinden gelmiş tema-tr_TR.l10n.php dururken siz yalnızca tema-tr_TR.mo dosyasını değiştirirseniz WordPress hâlâ eski .l10n.php dosyasını okur. Düzenlemeniz uygulanmamış gibi görünür. Duyuru bu senaryoyu adıyla anmıyor ama “.l10n.php varsa o yüklenir” kuralının doğrudan sonucu budur.

Çözüm yolları şunlar.

• Düzenlediğiniz .po dosyasından PHP dosyasını da yeniden üretin. Duyuruda bunun için WP-CLI’daki wp i18n make-php komutu gösterilir.
• Ya da eski .l10n.php dosyasını silin. WordPress bu durumda .mo dosyasını kullanır.

Bu iki yol da, dil paketi varsa, bir sonraki paket güncellemesine kadar geçerlidir. Duyuru ayrıca güncelleme denetimlerinin hâlâ .po ve .mo dosyalarına baktığını söyler, yani klasörden .po ve .mo dosyalarını kaldırıp yalnızca PHP dosyası bırakmak önerilen bir yol değildir.

Belirli bir sunucuda PHP biçimini tamamen kapatmak gerekirse 6.5 ile gelen translation_file_format filtresi mo değeriyle bu işi yapar. Bu, sorunu çözmekten çok saklar, ilk tercih olmamalı.

Dil paketi varken kendi çevirinizi kullanmak

Paketin üzerine yazmadığı ayrı bir klasör kullanıp WordPress’e oradaki dosyayı okutmanın resmî yolu load_translation_file filtresidir. WordPress 6.5’te geldi, 6.6’da yerel kod parametresi eklendi. load_textdomain() her aday dosya için bu filtreyi çalıştırır ve dönen yolu yükler. Filtre .mo ya da .l10n.php yolu döndürebilir.

Aşağıdaki küçük eklenti wp-content/mu-plugins/ klasörüne konur (bu klasördeki dosyalar her istekte kendiliğinden çalışır ve panelden kapatılamaz). ornektema yerine temanızın metin alanını yazın. Kod, filtrenin üçüncü parametresi olan yerel kodu kullandığı için WordPress 6.6 ve sonrası içindir. Canlı siteye koymadan önce bir deneme kurulumunda sınayın.

<?php
/**
 * Plugin Name: Özel tema çevirisi
 */
add_filter( 'load_translation_file', function ( $file, $domain, $locale ) {
	if ( 'ornektema' !== $domain || 'tr_TR' !== $locale ) {
		return $file;
	}
	$ozel = WP_CONTENT_DIR . '/ozel-ceviriler/ornektema-tr_TR.mo';
	return is_readable( $ozel ) ? $ozel : $file;
}, 10, 3 );

Bu yöntemin iki sınırı var.

• Bu kod paketi tamamen devre dışı bırakır, iki dosyayı birleştirmez. Özel dosyanız eksiksiz olmalı. En kolay yol, mevcut paketteki .po dosyasını kopyalayıp yalnızca düzeltmek istediğiniz satırları değiştirmek ve .mo dosyasını yeniden derlemektir.
• Tema yeni dizeler eklediğinde bu dizeler sizin dosyanızda olmayacağı için İngilizce görünür. Kendi dosyanızı tema güncellemelerinden sonra yeni şablonla (.pot) karşılaştırıp güncellemeniz gerekir.

Tek tük düzeltmeler için bu bakım yükü çoğu zaman gereksizdir. Yanlış ya da eksik çeviriyi translate.wordpress.org’da düzeltmek, düzeltmenin bir sonraki paketle tüm Türkçe sitelere ulaşmasını sağlar. Hesap açmaktan öneri göndermeye kadar adımları tema çevirisine katkı yazısında anlattık. Çevirisi %90’a birkaç dize uzaklıktaki temaları ise eşiğe yakın temalar listesinde topladık.

Kontrol sırası

Türkçe çeviri güncellemeden sonra kaybolduysa ya da hiç görünmüyorsa şu sırayla bakın.

1. Site dili. Ayarlar > Genel’deki site dili Türkçe mi, profilinizin dili ne? Panelin dili profil diline göre değişebilir, ayrıntılar site dili ayarları yazısında.
2. Dosyanın yeri ve adı. Dosya tema klasöründeyse güncellemede gitmiştir. Ortak klasördeyse adı <textdomain>-tr_TR.mo mu?
3. Metin alanı. style.css içindeki Text Domain: değeri dosya adındaki önekle birebir aynı mı?
4. .l10n.php dosyası. Aynı klasörde aynı adlı ve daha eski tarihli bir .l10n.php var mı?
5. Dil paketi. Tema için Türkçe paket varsa son çeviri güncellemesi dosyanızın üzerine yazmış olabilir. Değiştirme tarihine bakın.