Bir Tema veya Eklenti İçin .pot Dosyası Nasıl Oluşturulur?
Dünyayla paylaşmak istediğiniz bir WordPress eklentisini yeni bitirdiniz. Kod çalışıyor, özellikler sağlam ve Almanya'dan biri Almancaya nasıl çevrileceğini soran bir e-posta gönderiyor. Onları languages klasörüne yönlendiriyorsunuz ve orada hiçbir şey olmadığını fark ediyorsunuz. Şablon yok, dizeler yok, bir çevirmenin neyin çevrilmesi gerektiğini bile bilebileceği bir yol yok. Eklentiniz teknik olarak sadece "çeviriye hazır" görünüyor.
Her çevrilebilir WordPress projesi tek bir dosya ile başlar: .pot şablonu. Kimse Almanca, Fransızca veya Japonca bir sürüm oluşturmadan önce, kodunuzdaki her kullanıcıya dönük dizeyi listeleyen bir POT dosyası oluşturmanız gerekir. Bu adımı atlarsanız, çevirmenler kaynağınızı satır satır okumak zorunda kalacak ve hangi dizelerin görünür olması gerektiğini tahmin etmeye çalışacaklardır.
Bu rehber, işin iki yarısını ele alıyor: dizelerin bulunabilir olması için kaynak kodunuzu hazırlamak ve ardından .pot dosyasını üç farklı araçla oluşturmak. Kopyalayabileceğiniz gerçek komutlarla WP-CLI, Poedit ve eski makepot/grunt yaklaşımını kullanacağız. Sonunda herhangi bir çevirmene vermeye hazır, temiz bir şablona sahip olacaksınız.
Birinci Adım: Dizelerinizi Çevrilebilir Olarak İşaretleyin
Bir POT dosyası oluşturmadan önce, bir kullanıcının görebileceği her dize bir Gettext fonksiyonuyla sarmalanmalıdır. Bir tarayıcı yalnızca tanıdığı dizeleri çıkarabilir ve bunları bu fonksiyon çağrılarıyla tanır — düz dize sabitleri ona görünmezdir.
WordPress, her biri biraz farklı bir bağlam için bir dizi yerelleştirme fonksiyonu sunar:
// Return a translated string
$label = __( 'Add to Cart', 'my-plugin' );
// Echo a translated string directly
_e( 'Your cart is empty', 'my-plugin' );
// Translate with context to disambiguate identical words
$verb = _x( 'Post', 'verb: to publish', 'my-plugin' );
// Translate AND escape for safe HTML output
echo esc_html__( 'Welcome back', 'my-plugin' );
Her çağrıdaki ikinci argüman — 'my-plugin' — metin alanıdır. Bir eklentinin veya temanın tüm dizelerini tek bir ad alanı altında gruplar, böylece WordPress onlar için hangi .mo dosyasını yüklemesi gerektiğini bilir. Projenizdeki her çevrilebilir dize aynı metin alanını paylaşmalıdır, aksi takdirde bazı dizeler asla çevrilmeyecektir.
Bir kelime belirsiz olduğunda _x() kullanın. İngilizce "Post" bir isim veya fiil olabilir ve birçok dilde farklı çevrilir. Bağlam dizeleri çevirmenlerin bunları ayırt etmesini sağlar. Çevrilen dize HTML'ye yazdırıldığında ise esc_html__() ve esc_attr__() varyantlarını tercih edin, böylece aynı anda hem güvenli hem de yerelleştirilmiş kalırsınız.
Dizelerinizi çıkarılabilir tutan birkaç alışkanlık vardır. İlk argüman olarak her zaman düz bir dize sabiti geçirin — asla __( 'Hello ' . $name, 'my-plugin' ) gibi bir değişken veya birleştirmeyi kullanmayın, çünkü tarayıcı kaynak metni statik olarak okur ve çalışma zamanı değerlerini çözemez. Sayı içeren cümleler için, çoğul formların doğru bir şekilde yakalanması için _n() kullanın ve dinamik değeri olan cümleler için, dizeleri birbirine yapıştırmak yerine %s gibi bir yer tutucunun etrafında sprintf() kullanın. Buradaki tutarlılık, bir sonraki adım olan şablon oluşturmanın eksiksiz, kullanılabilir bir sonuç üretmesini sağlar.
İkinci Adım: Üstbilginizde Metin Alanını Bildirin
WordPress, çevirilerinizin nerede bulunduğunu bilmek için iki üstbilgi alanına ihtiyaç duyar: Metin Alanı (Text Domain) ve Alan Yolu (Domain Path). Bunları eklentinizin ana dosyasında veya temanızın style.css dosyasında ayarlayın, böylece WordPress çalışma zamanında doğru .mo dosyasını otomatik olarak yükleyecektir.
<?php
/**
* Plugin Name: My Plugin
* Description: A perfectly localized WordPress plugin.
* Version: 1.0.0
* Requires at least: 6.4
* Text Domain: my-plugin
* Domain Path: /languages
*/
Metin Alanı (__() ve _e() çağrılarına geçirdiğiniz dizeyle — burada my-plugin ile eşleşmelidir. Alan Yolu, WordPress'e çeviri dosyalarını eklenti veya tema kök dizinine göre hangi alt klasörde tuttuğunu söyler. Gelenek /languages'tır ve oluşturduğunuz .pot dosyanız tam olarak orada bulunmalıdır.
Dizeler sarılmış ve üstbilgi bildirilmişken, kodunuz taranmaya hazırdır. Bir projeyi çeviriye hazırlamanın daha geniş resmi — size ait olmayan temalar da dahil olmak üzere — geliştirici olmasanız bile herhangi bir WordPress temasını nasıl yerelleştireceğiniz makalesinde ele alınmıştır.
.pot Dosyası Nasıl Oluşturulur? Üç Yöntem
Bir .pot dosyası, kaynak kodunuz üzerinde her Gettext çağrısını bulan ve dizeleri bir şablona yazan bir tarayıcı çalıştırarak oluşturulur. İşte bunu yapmanın, modern varsayılandan eski yaklaşıma kadar üç güvenilir yolu.
Yöntem 1: WP-CLI (Önerilen)
Bir POT dosyası oluşturmanın resmi, modern yolu i18n komutunu içeren WP-CLI'dır. WordPress çekirdek araçlarının bir parçası olarak gelir, PHP ve JavaScript dizelerini anlar ve tek bir satırda standartlara uygun bir şablon üretir.
# Run from your plugin or theme root directory
wp i18n make-pot . languages/my-plugin.pot
# Add a text domain explicitly if auto-detection misses it
wp i18n make-pot . languages/my-plugin.pot --domain=my-plugin
# Scan only specific paths and exclude vendor folders
wp i18n make-pot . languages/my-plugin.pot --exclude=vendor,node_modules
İlk argüman kaynak dizin (mevcut klasör için .), ikincisi ise çıktı yoludur. WP-CLI dosyalarınızı tarar, sarılı her dizeyi çıkarır, kaynak dosyayı ve satır numarasını yorum olarak kaydeder ve .pot dosyasını yazar. Hızlıdır, komutlarla çalıştırılabilir ve her ciddi proje için doğru seçimdir.
Oluşturulan şablon, ek bayraklarla ayarlayabileceğiniz faydalı meta veriler içerir. Proje adını, sürümünü ve çevirmenlerin iletişim adresini ayarlamak için --headers argümanını geçirin, böylece .pot başlık bloğu yer tutucu olarak bırakılmak yerine doğru şekilde doldurulur. WP-CLI ayrıca wp_set_script_translations() çağrılarından JavaScript dizelerini otomatik olarak çıkarır; bu, kullanıcıya dönük metnin yarısının PHP yerine JavaScript'te bulunduğu modern blok temaları ve Gutenberg eklentileri için önemlidir. Tek bir komut her iki dünyayı da kapsar.
Yöntem 2: Poedit (Grafiksel)
Bir masaüstü uygulamasını tercih ediyorsanız, Poedit kaynağınızı tarayabilir ve arayüzü aracılığıyla şablonu oluşturabilir. Poedit'i açın, POT'tan yeni bir çeviri oluşturmayı veya kaynakları doğrudan taramayı seçin, proje klasörünüzü işaret edin ve katalog özelliklerinin altında kaynak anahtar kelimeleri (__, _e, _x, esc_html__) yapılandırın.
Poedit'in kaynak tarama ve .pot oluşturma özellikleri Pro sürümünde bulunur, ancak iş akışı komut yazmak yerine tıklamayı tercih eden geliştiriciler için dostane bir yapıdadır. Ayrıca, takip eden çeviri aşaması için sağlam bir düzenleyicidir. Poedit ve diğer bazı masaüstü seçenekleri Mac ve Windows'ta PO dosyalarını düzenlemek ve çevirmek için en iyi 5 ücretsiz araç makalesinde karşılaştırılmıştır.
Yöntem 3: makepot / grunt (Eski Nesil)
WP-CLI'dan önce, standart araç WordPress i18n-tools deposundan alınan makepot.php betiğiydi, genellikle grunt-wp-i18n ile bir Grunt derleme görevine entegre edilirdi. Onu hala eski eklentilerde ve temalarda göreceksiniz.
# Legacy makepot.php invocation
php makepot.php wp-plugin /path/to/my-plugin languages/my-plugin.pot
Çalışır, ancak WP-CLI'ye göre bakımı yapılmamıştır ve kurulumu daha yavaştır. Yalnızca ona zaten bağlı olan eski bir projeyi sürdürürken kullanın; yeni bir şey için wp i18n make-pot komutunu tercih edin.
Kodunuz Değiştikçe Şablonu Güncel Tutun
Bir .pot dosyası, dizelerinizin belirli bir andaki anlık görüntüsüdür. Her yeni özellik eklediğinizde, bir etiketi değiştirdiğinizde veya görünür bir dizedeki yazım hatasını düzelttiğinizde, şablon güncelliğini yitirir ve çevirmenler yeni ifadeleri kaçırır.
Yeniden oluşturmayı sürüm rutininizin bir parçası haline getirin. Her sürüm artışından önce wp i18n make-pot komutunu tekrar çalıştırın, ardından yenilenen şablonu wp i18n update-po veya msgmerge ile mevcut çevirilere birleştirin, böylece çevirmenler bitmiş işlerini korur ve yalnızca yeni boşlukları görürler. .pot dosyasını elle düzenlediğiniz bir dosya değil, yeniden oluşturduğunuz bir derleme yapısı olarak değerlendirin.
Eski bir şablon, ince ama sinir bozucu bir hataya neden olur: yeni dizeler, çevirmenin çalıştığı .pot dosyasında hiç bulunmadığı için "tamamen çevrilmiş" bir sitede bile İngilizce olarak görünür. Bunu yakalamak, yeniden oluşturmayı derlemenize betik olarak eklemek kadar basittir, böylece şablon hiçbir zaman kodun gerisinde kalmaz. Bazı ekipler, .pot dosyasını yeniden oluşturmanın bir fark üretmesi durumunda derlemeyi başarısız eden bir CI kontrolü ekleyerek, kaydedilen şablonun her zaman mevcut kaynakla eşleşmesini garanti eder.
Çevirmenler tamamlanmış .po dosyalarını iade ettikten sonra, bunların WordPress'in gerçekten yüklediği ikili .mo dosyasına derlenmesi gerekir — ve tüm indirme-çevirme-yeniden derleme döngüsünü atlamak isterseniz, bir bulut aracı bunu baştan sona halledebilir. SimplePoTranslate, .pot dosyanızı doğrudan kabul eder, arayüzünüzdeki her dizenin ne anlama geldiğini anlayan Bağlama Duyarlı Yapay Zeka (Context-Aware AI) ile çevirir ve .po, .mo ve daha fazlası zaten oluşturulmuş ve adlandırılmış tek bir ZIP dosyası döndürür. Sözdizimi Kilitleme (Syntax Locking) özelliği, %s ve %1$s gibi yer tutucuları dondurarak değişkenlerinizin çeviride asla bozulmamasını sağlar.
Sonuç
Doğru şekilde bir POT dosyası oluşturmak için öncelikle kodunuzu keşfedilebilir hale getirin — her görünür dizeyi __(), _e(), _x() veya bir kaçış varyantıyla sarmalayın, hepsi tek bir metin alanını paylaşsın ve bu alanı artı Domain Path'i üstbilginizde bildirin. Ardından, yeni projeler için WP-CLI ile, GUI'yi tercih ediyorsanız Poedit ile veya yalnızca eski kodu sürdürüyorsanız makepot ile şablonu oluşturun.
Erken oluşturun, sık sık yeniden oluşturun ve şablonunuzun asla kodunuzun gerisinde kalmasına izin vermeyin. Güncel bir .pot dosyası, dünyaya gerçekten hazır bir eklenti ile sadece öyle olduğunu iddia eden bir eklenti arasındaki farktır.
.potşablonunuzu manuel derleme derdini çekmeden bitmiş çevirilere dönüştürmeye hazır mısınız? SimplePoTranslate'i ücretsiz deneyin — kredi kartı gerekmez. Şablonunuzu ücretsiz katmana yükleyin ve dakikalar içinde gönderime hazır çeviri dosyalarını indirin.