Türkçe dilini kullanmayan ülkeleri düşündüğümüzde ve sitemizi dünyaya açmak istediğimizde, internet sitemizin başka dillerde, özellikle de İngilizce dilinde yayın yapmasının önemi ortaya çıkar.

Biz bu başlıkta, WordPress temamızı nasıl tercüme edeceğimizi değil, tercümeye hazır bir şekilde nasıl kodlayacağımızı açıklayacağız. Bu dersi anladığınızda, hazırladığınız tema, özüne dokunmadan, eklentiler veya tercümanlar yardımı ile rahatça tercüme edilebilecektir.

Temayı Tercümeye Hazır Halde Kodlama

Tercümeye hazırlama kavramı, İngilizce dilinde “internationalization” kelimesine karşılık gelir. Bu kelime de i18n şeklinde kısaltılır. i18n ifadesi, internationalization kelimesinin başı ve sonundaki i ve n harfleri ile bu ikisi arasındaki 18 harf düşünülerek oluşturulmuştur.

Temalarda tercüme gerektiren yerler metinler, bir başka ifade ile textlerdir. Dolayısıyla, bir temayı tercümeye hazır halde kodlamak demek, temamızda geçen metinleri tercümeye hazır halde kodlamak demektir.

Bir metni, tercümeye hazır halde kodlamak, tamamen bu iş için üretilmiş WordPress fonksiyonlarının marifetidir.

Tercümeye Hazır Textler Oluşturan Fonksiyonlar

Aşağıda verilen fonksiyonlar, textleri, sadece tercümeye hazır halde kodlamaya değil, aynı zamanda, tercüme işlemi bittiğinde, tercüme edilmiş bir biçimde getirmeye yararlar.

• __()
• _e()
• _n()
• _x()
• _ex()
• _nx()
• _n_noop()
• _nx_noop()
• translate_nooped_plural()

Mesela, şablon dosyamızda şöyle bir başlık kodladığımızı varsayalım:

<h1>WordPress Tema Yapımı</h1>

Yukarıda gördüğümüz başlıktaki “WordPress Tema Yapımı” textini tercüme etmek istediğimizde, bu HTML elemanının bulunduğu şablon dosyasını bulup açmak ve manuel olarak tercüme etmek zorundayız. Daha sonra başka bir dile tercüme etmek gerektiğinde de, yine aynı işlemi uygulamamız gerekecektir. Fakat, aynı HTML elemanını şu şekilde kodlarsak:

<h1><?php echo __('WordPress Tema Yapımı', 'textdomain'); ?></h1>

veya şu şekilde kodlarsak:

<h1><?php _e('WordPress Tema Yapımı', 'textdomain'); ?></h1>

başlığımızı, tercümeye hazır olarak kodlamış oluruz. Ve bir tercümeye ihtiyacımız olduğuna, bu başlığın bulunduğu şablon dosyasını bulup, tekrar düzenlemeye hiç ihtiyacımız kalmaz.

Tercümeye Hazır Textler

Aşağıda belirtilen metinler tercümeye uygundur:

$textim = __('WordPress Tema Yapımı', 'textdomain');

echo __('WordPress Tema Yapımı', 'textdomain');

_e('WordPress Tema Yapımı', 'textdomain');

“Textdomain” Parametresi

Tercümeye hazır textler için kullandığımız fonksiyonların ikinci parametresi, bir 'textdomain'dir. Textdomainler, bizim belirlediğimiz, Türkçe karakter ve boşluk içermeyen string (text) tipindeki ifadelerdir.

Her temanın, diğer temalardan farklı bir textdomain değeri vardır. Textdomainler, WordPress’in, tema ya da eklentiye özgü tercümeleri saptayabilmesini sağlar, farklı temaların ya da eklentilerin tercümelerinin birbirine karışmasını engeller.

Temanızı, https://wordpress.org/themes/ adresinde ve tercüme edilmiş bir şekilde depolamak istiyorsanız, temanızın textdomain değeri, URL ifadesinin sonunda bulunan link adı ile aynı olmalıdır. Mesela, temanızın URL ifadesi https://wordpress.org/themes/benim-temam şeklinde ise, textdomaini de 'benim-temam' olmalıdır.

Textdomain ifadesi, genellikle, temaya verilen ad ile aynı olacak şekilde ayarlanır. Textdomain ifadeleri, tire (-) işareti ve küçük harflerden oluşabilir, alt tire ve büyük harfler içermemelidir.

Bir temamız olsun, benim-temam adlı bir klasörde oluşturulmuş olsun ya da style.css dosyasında Benim temam olarak kaydedilmiş olsun. Bu tema için, oluşturulabilecek textdomain ifadelerinin doğru ve yanlış şekilleri şöyledir:

• 'benim-temam' : Doğru
• 'Benim-temam' : Yanlış
• 'benim_temam' : Yanlış

Bir WordPress temasında, textdomain ifadesi üç farklı yerde kullanılır:

1. Temanın temel stil dosyası olan style.css dosyasında
2. Tercümeye hazır textler oluşturan fonksiyonlarda
3. Temamıza tercümeleri yüklemek için kullandığımız, load_theme_textdomain() ve load_child_theme_textdomain() fonksiyonlarında parametre olarak

Texdomainin kullanıldığı bu 3 yeri sırasıyla görelim:

I- Temel Stil Dosyası: style.css

Temel stil dosyası, her temanın zorunlu iki dosyasından biridir ve adı her zaman style.css olarak verilir.

Style.css dosyaları her zaman, çoklu bir PHP yorumu ile başlar ve bu yorum kısmında tema hakkında meta bilgiler bulunur. Bu meta bilgilerden biri de temanın textdomain ifadesidir. Sırasıyla; temanın adı, yazarı ve textdomain ifadesinden oluşan meta bilgileri ile birlikte, style.css dosyasının yorum kısmı şuna benzer:

/*
* Theme Name: Benim Temam
* Author: Adım SOYADIM
* Text Domain: benim-temam
*/

Domain Path

Style.css dosyasında verilebilen bir diğer meta bilgisi de, Domain Path yani dil dosyalarımızın barındırıldığı klasörün adıdır. Eğer dil dosyalarımızı, languages değil de başka bir isimde bir klasörün içinde barındırmak istersek, Domain Path metası ile bu klasörün adını WordPress’e öğretiyoruz. Çünkü, WordPress, varsayılan olarak dil dosyalarımızı, temamızın ana dizininde ve languages klasöründe arar. Aşağıda Domain Path metası ile birlikte bir style.css dosyası örneği verilmiştir:

/*
* Theme Name: Benim Temam
* Author: Adım SOYADIM
* Text Domain: benim-temam
* Domain Path: /languages
*/

II- Tercümeye Hazır Textler Oluşturan Fonksiyonları

Bu başlıkta bahsedilen fonksiyonları hatırlamak için yukarıya bakabilirsiniz.

III- Tercümeleri Yükleme

Temamızı tercüme ederken oluşturduğumuz .mo ve .po dosyalarının çalışması için yüklenmesi gerekir. Bu dosyaların yüklenmesi için kullanılan iki adet fonksiyon vardır. Bu fonksiyonlar şunlardır:

1. Load_theme_textdomain(): Ana tema için oluşturduğumuz tercüme dosyasını yükler.
2. Load_child_theme_textdomain(): Yavru tema için oluşturduğumuz tercüme dosyasını yükler.

Bu fonksiyonların dil dosyalarınızı doğru yükleyebilmesi için, dil dosyaların adını doğru koymanız gerekmektedir. Dil dosyalarınızın adını koyarken şunlara dikkat etmelisiniz:

I- Tercüme dosyanız (.mo), tema dizininde ise, dosyanızın adlandırma formatı şu şekilde olmalıdır:

{dil_kodu}.mo

Aşağıda bu formatta verilmiş örnekler vardır:

• Fransızca için: fr_FR.mo
• Amerikan İngilizcesi için :  en_US.mo
• Türkçe için: tr_TR.mo

II- Tercüme dosyanız (.mo), tema dizininizde değil de, WordPress’in tercümeler için kullandığı /wp-content/languages/themes/ dizininde ise, dil dosyanızın adlandırma formatı şu şekilde olmalıdır:

{textdomain}-{dil_kodu}.mo

Örnek-1

Load_theme_textdomain() fonksiyonu, functions.php dosyasında ve temel olarak şu şekilde kullanılır:

add_action('after_setup_theme', 'ilktemam_setup');
 
/**
 * ilktemam için tercümeleri yükler
 * Tercüme dosyası (.mo) dizini için varsayılan olarak tema dizinindeki languages klasörü gösterilmiştir.
 */
function ilktemam_setup(){
    load_theme_textdomain('ilktemam-textdomain', get_theme_file_path() . '/languages');
}

Örnek-2

Load_child_theme_textdomain() fonksiyonu, functions.php dosyasında ve temel olarak şu şekilde kullanılır:

add_action('after_setup_theme', 'ilktemam_setup');
 
/**
 * ilktemam için tercümeleri yükler
 * Tercüme dosyası (.mo) dizini için varsayılan olarak yavru tema dizinindeki languages klasörü gösterilmiştir.
 */
function ilktemam_setup(){
    load_child_theme_textdomain('ilktemam-textdomain', get_theme_file_path() . '/languages');
}

Güvenli Tercüme

Metinleri tercüme hazırlayan fonksiyonların, güvenlik önlemleri ile geliştirilmiş halleri de vardır. Bu fonksiyonlar, tercüme işlemi esnasında oluşabilecek güvenlik zaafiyetlerini veya hataları engellerler. Bahsettiğimiz bu fonksiyonlar şunlardır:

• esc_html__()
• esc_html_e()
• esc_html_x()
• esc_attr__()
• esc_attr_e()
• esc_attr_x()

Sayıların Tercümesi

Sayıların yazım biçimi, özellikle ondalık sayıların yazım biçimi, ülkeden ülkeye değişebilmektedir. WordPress, bu durumu göz önüne alarak, metinler gibi, sayıları da tercüme edecek bir fonksiyon üretmiştir. Bu fonksiyon şudur:

• number_format_i18n()

Tarih Textinin Tercümesi

Gün isimleri, hafta isimleri, belki de bazı diller için, tarih ifade eden textin tamamı, tercüme gerektiren tarih elemanlarıdır. WordPress, bir tarih textindeki elemanları, sitenin diline göre, otomatik olarak tercüme eden şu fonksiyon ile birlikte gelir:

• date_i18n()

Değişken İçeren Textlerin Tercümesi

PHP değişkeni içeren metinler, temalarda sıkça kullanılan ifadelerdir. Aşağıda böyle bir metin verilmiştir:

echo "Hoşgeldiniz $uye_adi.";
// veya aynı metni şöyle de yazabiliriz
echo 'Hoşgeldiniz '. $uye_adi;

Değişkenli metinleri, tercümeye hazır olarak kodlamak için, prinf() veya sprintf() fonksiyonlarından yararlanılır. Bu iki fonksiyon, WordPress’in değil, PHP diline ait fonksiyonlardır.

Bu fonksiyonlar, metinlerin içine, değişkenler için yer tutucular yerleştirmemize izin verir.

Örneğe dikkat edelim:

printf( __( 'Hoşgeldiniz %s.', 'ilktemam' ), $uye_adi );

Printf() fonksiyonunun ilk parametresi, yer tutucu (%s) ile birlikte ve tercümeye hazır şekilde bir metindir, ikinci parametresi ise yer tutucu ifadenin yerine geçecek değişken olur.

Printf() veya Sprintf() Fonksiyonlarında Kullanılan Yer Tutucular

Yer tutucular, özel bir takım ifadelerdir ve belli bazı karakterlerden oluşurlar. Yerini tuttukları değişkenin tipine bağlı olarak, karakter yapıları da değişmektedir.

Aşağıda, prinf() veya sprintf() fonksiyonlarında kullanılan yer tutucuların oluştuğu karakterler ve anlamları verilmiştir:

• %% – Bir yüzde (%) işareti döndürür
• %b – Binary (ikilik) tipinde bir sayının yerini tutar
• %c – ASCII değerine uygun herhangi bir karakterin yerini tutar
• %d – Bir tam sayının yerini tutar (negatif, sıfır veya pozitif bir sayı)
• %e – Küçük harf kullanarak, bilimsel bir ifadenin yerini tutar (örn. 1.2e+2)
• %E – Büyük harf kullanarak, bilimsel bir ifadenin yerini tutar (örn. 1.2E+2)
• %u – Pozitif tam sayıların yerini tutar. (sıfır ve sıfırdan büyük sayılar)
• %f – Küsürlü veya noktalı (floating-point) sayıların yerini tutar (yerel dile uygun olarak tercüme eder)
• %F – Küsürlü veya noktalı (floating-point) sayıların yerini tutar (tercüme etmez)
• %g – %e ve %f yer tutucularının kısaltmasıdır
• %G – %E ve %f yer tutucularının kısaltmasıdır
• %o – Sekizlik tabanda bir sayının yerini tutar
• %s – String (text) tipinde bir değişkenin yerini tutar
• %x – 16 tabanlı bir sayının yerini tutar. (küçük harfler ile)
• %X – 16 tabanlı bir sayının yerini tutar. (büyük harfler ile)

Yer tutuculara belli bir format vermemizi sağlayan yardımcı elemanlar:

Yer tutucular ile birlikte kullanılan ve yer tutucunun belli bir takım özellikler kazanmasını sağlayan bazı PHP işaretleri vardır. Bu işaretler yer tutucunun % işareti ile harfi arasında kullanılır. Aşağıda, bahsettiğimiz bu işaretler ve anlamları verilmiştir:

• + işareti: Sayının önünde + veya – işaretinin görünmesini sağlar. Varsayılan olarak, sayıların önünde, varsa, sadece – işaretleri görünür.
• ‘ işareti: Boşluk olarak ne kullanacağımızı belirler. Varsayılan boşluk değeri boş karakterdir. Genişlik belirtilerek kullanılmalıdır. (Örnek: %'x20s yer tutucusunda, değişkenden gelen textin minimum uzunluğu 20 karakter olacak şekilde ayarlanır ve bu uzunluğa erişmesi için boşluk eklemek gerekiyorsa da boşluk karakteri olarak “x” harfi kullanılır.)
• – işareti: Değişkenin değerini sola yaslayarak gösterir.
• [0-9] tüm sayılar: Değişkenin değerinin alması gereken minimum uzunluğu ifade eder.
• .[0-9] şeklinde tüm sayılar: Ondalık sayıların uzunluğunu veya textin maksiumum uzunluğunu belirler.

Birden Çok Değişken İçeren Textlerin Tercümesi

Birden çok değişkenli metinleri, tercümeye hazır olarak kodlamak için de prinf() veya sprintf() fonksiyonlarından yararlanılır. Çoklu yer tutucu içeren textlerde kaç tane yer tutucu varsa, textin ardından, fonksiyona, o kadar parametre daha eklenir.

Aşağıdaki kodda iki farklı değişken için iki yer tutucu kullanılmıştır:

$uye_adi = "Adım SOYADIM";
$siparis_no = 12345;

printf( __( 'Hoşgeldiniz sayın %s. Sipariş numaranız: %u', 'ilktemam' ), $uye_adi, $siparis_no );

// Çıktısı
// Hoşgeldiniz sayın Adım SOYADIM. Sipariş numaranız: 12345

Aşağıdaki örnekte aynı tipten iki yer tutucu kullanılmıştır:

$uye_adi = "Adım SOYADIM";
$il = 'BENİM İLİM';
printf( __( 'Hoşgeldiniz sayın %s. Kayıtlı olduğunuz il: %s', 'ilktemam' ), $uye_adi, $il );

// Çıktısı
// Hoşgeldiniz sayın Adım SOYADIM. Kayıtlı olduğunuz il: BENİM İLİM

Peki aynı kodu, printf() fonksiyonundaki değişkenlerin yerlerini değiştirerek kullanırsak ne olur:

$uye_adi = "Adım SOYADIM";
$il = 'BENİM İLİM';
printf( __( 'Hoşgeldiniz sayın %s. Kayıtlı olduğunuz il: %s', 'ilktemam' ), $il, $uye_adi);

// Çıktısı
// Hoşgeldiniz sayın BENİM İLİM. Kayıtlı olduğunuz il: Adım SOYADIM

Böyle bir hatadan kurtulmak için yer tutuculara 1$, 2$, 3$… şeklinde numaralar verebiliriz. Bu numaralar, textin içinde sırayla verilmese bile, değişkenleri her zaman bir numaralı olandan başlayarak numara sırasına göre yer değiştirir. Yani, ilk değişken, her zaman numarası 1$ olan yer tutucu ile, ikinci değişken numarası 2$ olan yer tutucu ile… yer değiştirir. Bu durumu şöyle de ifade edebiliriz:

printf( 'yer %2$s tutucu içeren text %1$s', $bir_numarali_yer_tutucuya_ait, $iki_numarali_yer_tutucuya_ait, .... )

Aşağıdaki örneğe dikkat edelim:

$uye_adi = "Adım SOYADIM";
$il = 'BENİM İLİM';
printf( __( 'Hoşgeldiniz sayın %2$s. Kayıtlı olduğunuz il: %1$s', 'ilktemam' ), $il, $uye_adi);

// Çıktısı
// Hoşgeldiniz sayın Adım SOYADIM. Kayıtlı olduğunuz il: BENİM İLİM

Tek Tırnak – Çift Tırnak Farkı

Yer tutuculara numara verdiğimizde, bu yer tutucuların textlerini tek tırnak içine almamız gerekmektedir. Çünkü, çift tırnak içinde iken PHP $s ifadesini bir değişken olarak değerlendirir, yer tutucu olarak anlamaz.

Aşağıdaki örnekte, yer tutucular çalışmaz:

$uye_adi = "Adım SOYADIM";
$il = 'BENİM İLİM';
printf( __( "Hoşgeldiniz sayın %2$s. Kayıtlı olduğunuz il: %1$s", 'ilktemam' ), $il, $uye_adi);

// Çıktısı
// Hoşgeldiniz sayın Kayıtlı olduğunuz il:

İlle de çift tırnak kullanmak istersek, kaçma işareti (\) işimizi görecektir:

$uye_adi = "Adım SOYADIM";
$il = 'BENİM İLİM';
printf( __( "Hoşgeldiniz sayın %2\$s. Kayıtlı olduğunuz il: %1\$s", 'ilktemam' ), $il, $uye_adi);

// Çıktısı
// Hoşgeldiniz sayın Adım SOYADIM. Kayıtlı olduğunuz il: BENİM İLİM

Aşağıdaki kod, çalışır fakat tercüme için uygun değildir:

$uye_adi = "Adım SOYADIM";
_e( "Hoşgeldiniz sayın $uye_adi", "ilktemam" );

// Çıktısı
// Hoşgeldiniz sayın Adım SOYADIM

Tekil – Çoğul Hallerin Tercümesi

Özellikle İngilizce diline tercüme ederken, bir kelimenin tekil kullanımı ile çoğul kullanımını ayrı ayrı tercüme etmemiz gerekmektedir. WordPress’in sunduğu _n() fonksiyonu, bu işi, kelimenin önündeki sayıya göre, dinamik olarak yapmaktadır.

Aşağıda, yorum (comment) sayısına göre, “comment” kelimesini tekil ya da çoğul durumuna göre tercüme eden bir örnek verilmiştir:

printf(
    _n(
        '%s comment',
        '%s comments',
         get_comments_number(),
        'ilktemam'
    ),
    number_format_i18n( get_comments_number() )
);

// Çıktı (5 yorum varken)
// 5 comments

// Çıktı (1 yorum varken)
// 1 comment

Sonraya Bırakılan Tekil – Çoğul Tercümesi

Bir kelimeyi, tekil ve çoğul halleri ile birlikte POT dosyasına kaydedip, gerektiğinde tercüme etmek de mümkündür. WordPress bunun için, _n_noop() ve _nx_noop() fonksiyonlarını geliştirmiştir.

Aşağıdaki kod, “comment” kelimesinin tekil ve çoğul yapısını POT dosyasına kaydeder.

$comments_tercumeleri = _n_noop(
    '%s comment.',
    '%s comments.'
);

“Comment” kelimesini, tekil ve çoğul yapıları ile tercüme etmek için, $comments_tercumeleri değişkenini, translate_nooped_plural() fonksiyonunda, ilk parametre olarak kullanmamız yeterlidir:

printf(
    translate_nooped_plural(
        $comments_tercumeleri,
        get_comments_number(),
        'ilktemam'
    ),
    number_format_i18n( get_comments_number() )
);

Kelime Anlamı İle İlgili Not Bırakma

Türkçe’de eşsesli yani farklı anlamları olan fakat aynı şekilde yazılan kelimeler, başka bir dile tercüme edilirken her anlamı için farklı kelimeler ile tercüme edilmeleri gerekir. Böyle kelimeler için, tercüme ediciye, hangi anlamı ile tercüme edileceğine dair bir ipucu vermek doğru bir tercüme açısından çok faydalı olacaktır. WordPress tam da bu iş için kullanılan _x() ve _ex() fonksiyonlarını üretmiştir.

Aşağıda, yüz kelimesi ipuçlarına uygun tercümeleriyle kullanılmıştır:

_x( 'Yüz', 'sayı olarak', 'ilktemam' );
_x( 'Yüz', 'vücudun parçası olarak', 'ilktemam' );

Tercümanlara Not Bırakma

Tercüme yapan kişilerin işini kolaylaştırmak adına, tercümeye hazırlanan textlere, başında translators: ifadesi olan bir PHP yorumu şeklinde not bırakmak iyi bir alışkanlıktır. Bıraktığınız bu notlar, temanın POT dosyasında görünecek ve tercümana yardımcı olacaktır. Aşağıda bu şekilde bir kod verilmiştir:

printf(
    /* translators: 1:Bir şehir adıdır 2:Kullanıcı ismidir */
    __( 'Merhaba sayın %2$s, kayıtlı olduğunuz şehir %1$s şehridir.', 'ilktemam' ),
    $sehir,
    $isim
);

Satır Başı (Newline) Karakteri

Tercüme edici fonksiyonlar satır başı için kullanılan \r karakterini hiç sevmezler. Bu yüzden satır başı yapmak istediğimizde bu karakterin yerine \n karakterini kullanmalıyız.

JavaScript Kodlarındaki Textlerin Tercümesi

JavaScript kodlarınızda geçen metinleri de tercüme fonksiyonları ile tercüme edebilirsiniz. WordPress bunun için wp_localize_script() fonksiyonunu üretmiştir.

Tercümeye En Uygun Metinler

Daha etkili tercümeler için, temanızı kodlarken kullandığınız dil önemlidir. Burada şu durumlara dikkat etmeniz tavsiye edilir:

• Açık bir dil kullanın, argo ve kısaltmalardan mümkün olduğunca uzak durun.
• Eksik cümleler kurmayın.
• Paragraflar kullanmaya dikkat edin.
• Tercüme edilecek metinlerin başında veya sonunda boş karakter bırakmayın.
• Tercüme edildiğinde, metinlerinizin iki kat büyüyebileceğini göz ardı etmeyin.
• Alışılmadık noktalama işaretleri veya başka işaretler kullanmayın.
• Tercüme edilen metinlerde, gereksiz HTML kullanımından sakının.
• URL ifadelerini tercümanlara bırakmayın.
• Değişkenleri, yer tutucular ile birlikte kullanmak daha iyidir:

Bu iyidir:

printf( 
    __( 'Şehriniz %1$s ve posta kodunuz %2$s.', 'ilktemam' ), 
    $sehir, 
    $posta_codu
); 

Aşağıdaki iyi değildir:

__( 'Şehriniz ', 'ilktemam' ) . $sehir . __( ' ve posta kodunuz ', 'ilktemam' ) . $posta_codu; 

• Yer tutucuların, cümledeki konumlarının diğer dillerde farklı olabileceğini dikkate alın:

printf(
    __( 'Şu kelime için arama sonuçları: %s', 'ilktemam' ),
    get_search_query()
);