PHP Belgeleri NASIL çevrilir?

PHP Belgelelerinin yapısı ve daha pek çok şey hakkında fikir edinmek için http://doc.php.net/tutorial/ adresindeki belgeyi okuyun.

Bizim çalışacağımız modülün ismi: doc-tr

Yani, çalışma dizininiz için komut satırından vereceğiniz komut: svn co http://svn.php.net/repository/phpdoc/modules/doc-tr

Bu komut doc-tr diye bir dizin açacak ve altına SVN deposundan bu modüle ait dosyaları indirecektir. Bundan sonra doc-tr dizininden bahsederken "çalışma dizini" diyeceğiz. Bunu yaptıktan sonra yeni bir çeviriye başlamaya karar vermeden önce çalışma dizininizde daima

svn update

komutunu vermelisiniz. Bu komut çalışma dizininizi son haline getirir. Onun için bir çeviriyi güncelliyorsanız bu komutu vermeyin. Yoksa çevirdikleriniz heba olabilir. tr/ dizininde sadece çevrilmiş ve çevirisi sürmekte olan dosyalar vardır. Yani çevireceğiniz dosya tr/ altında varsa başka bir dosya seçmeniz gerekecek. Çevireceğiniz dosyayı en/ dizini altından seçip tr/ altındaki yerine kopyalayacaksınız. Örneğin, 'doc-tr/en/reference/apache/book.xml' dosyasını gözünüze kestirdiniz diyelim. Yapacağınız, çalışma dizininizin içinde

cp en/reference/apache/book.xml tr/reference/apache/book.xml

komutunu vermeye eşdeğer bir işlem olacak.

SVN deposuyla çalışmak için masaüstü uygulamaları da var. Windows kullananlar için (GPL) http://www.tortoisesvn.net/ öneririm. Linux kullananlar için seçenek çok. KDE kullananlar için kdesvn'yi önerebilirim. RapidSVN'de fena değil ama kdesvn baha daha kullanışlı geldi. Masaüstü uygulamalar ilk update'i kendiliğinden yapıyormuş gibi görünebilir, buna aldanmayın. Yaptığı işlem çalışma dizininizi güncellemez sadece bilgi amaçlıdır. Sizi ilgilendiren değişiklikler olduğunu görüyorsanız bunları çalışma dizininize yansıtmak için update işlemini yinelemeniz gerekir.

Ama hemen çeviriye girişmeyeceksiniz. Bazı önişlemler var.

** Bundan sonrası SVN hesabı bulunanları da ilgilendiriyor. **

Dosyanın ilk satırı genelde şuna benzer bir girdi içerir:
<?xml version="1.0" encoding="utf-8"?>
Bu satıra "XML başlığı" diyelim.

Burada "utf-8", çeviri yaparken kullanacağınız karakter kodlamasıdır. Linux kullanıyorsanız, öntanımlı ayarları değiştirmediyseniz karakter kodlamanız UTF-8'dir. Windows kullanıyorsanız, muhtemelen CP1254'tür. Karakter kodlaması olarak UTF-8 kullanmayanlar iconv, recode gibi araçlarla karakter kodlamasını UTF-8'e çevirecekler. Şüphesiz bu amaçla PHP'yi de kullanabilirler ;-)

XML başlığının altında bulunan SVN sürüm satırına dokunmuyoruz. O satırı SVN günceller. O satır bundan sonra yaptığınız çevirinin sürümünü içerecek. O satırın altına şöyle bir satır ekleyin:

<!-- EN-Revision: 123456 Maintainer: flarecaster Status: ready -->

Bu satıra "güncelleme satırı" diyelim. '123456' özgün belgenin sürüm numarası,'flarecaster' çevirmenin translation.xml dosyasında yazan kullanıcı adı (nick), sonuncusu ise dosyanın durumunu gösterecek. Çeviriye başlarken oraya "wip", tamamlandığında "ready" yazacaksınız.

Böylece özgün belgenin sürüm numarası değiştiğinde en/ dizini altındaki dosya için

svn diff -r<EN-revision> <en/dizin/dosya>

komutuyla eski ve yeni sürümler arasındaki farkı kolayca görebilecek, tüm dosyayı yeni baştan çevirircesine elden geçirmekten kurtulacağız. Yani, çeviriyi güncellemek kolaylaşacak. Tabii, çeviriyi yapan güncelleyecek ;-)

Güncelleme sırasında 123456 yerine özgün belgenin yeni sürüm numarasını yazmayı unutmuyoruz.

Bu iki satır sayesinde çeviri istatistikleri oluşturuluyor:

Güncelleme satırının altında bazı dosyalarda

<!-- CREDITS: cumhuronat, tpug, antimon, flarecaster -->

gibi satırlar göreceksiniz. Bu kişiler o belgenin çevirisiyle evvelce ilgilenmiş kişilerdir. Onları böyle bir satırla hatırlamış oluyoruz.

Sıra geldi çeviride dikkat edilecek hususlara...
XML dosyalarla çalışırken dosyanın sekme karakterini (09) içermemesi gerekir. Eğer metin düzenleyiciniz yapabiliyorsa sekmeleri boşluklara çevirmeyi etkin kılın, yapamıyorsa bunu yapabilen bir metin düzenleyici bulun. Bulamıyorsanız, sekme yerine boşluk tuşuna basın. Zaten çalışacağınız XML dosyaların girintileri 1 karakter uzunlukta.

78 sütundan daha geniş satırlar kullanmayın. Uzun satırlar farkları komut satırından görmek istediğinizde işinizi kolaylaştırmayacaktır.

Dosyalar '<para>This extension requires PHP 5.</para>' şeklinde HTML'ye benzer etiketler arasında bir takım metinler içerir. Bu etiketler XML belgenin yapı taşları olduğundan onları çevirmeyeceğiz. Bazı etiketlerin HTML etiketlerindeki gibi öznitelikleri vardır, onlara da dokunmuyoruz. Yani, yukarıdaki metni <para>Bu eklenti PHP 5 gerektirir.</para> şeklinde çevireceğiz.

Ayrıca dosyalarda bazen & ile başlayıp ; ile biten bazı sözcüklere rastlayacaksınız. Onları cümlenin bir parçası haline getireceksiniz. Örneğin, <para>You must enable the <literal>foo</literal> setting in &php.ini;</para> yerine <para><literal>foo</literal> ayarını &php.ini; içinde yapmış olmalısınız.</para> yazacaksınız. Ancak bazı durumlarda bunu yapamayabiliriz. Değişken içindeki metin parçası cümle içinde kulanıldığında bir yerde doğruyken başka bir yerde imla hatasına yol açabilir. Böyle bir durumdan şüphe duyarsanız mevcut HTML belgeye bakıp ne yapacağınıza kendiniz karar vermelisiniz. XML belgeyle ilişkili HTML belgeye, genellikle, XML belgenin kök etiketindeki xml:id değerinin sonuna .html veya .php getirerek ulaşabilirsiniz.

Tırnak karakteri yerine &apos; kullanılmışsa siz de onu kullanın. Sizin cümle içinde tek tırnak imi kullanmanız gerekirse zor gelmeyecekse yine &apos; kullanın. Böylece `' gibi farklı tırnak imleri yerine tek bir tırnak imi kullanmış oluruz. Ayrıca XML belgelerin HTML veya PHP'ye dönüştürülmesi sırasında olası bir tırnak ayırma hatasını da önlemiş oluruz. Bu durum belgelerin kılavuz sayfaları üretilirken bilhassa önem kazanmaktadır. Kılavuz (man) sayfalarında ' iminden başkası (&apos; olur, kendileri) görüntülenmez. Yani &apos; yerine başka bir tırnak imi kullanmışsanız kılavuz sayfasında o tırnağı bulamayabilirsiniz.

Çeviri bittikten sonra güncelleme satırındaki 'wip' dizgesini 'ready' yapmayı unutmayın.

Linux kullananların çeviriyi kate üzerinde yapmasını öneririm. XML dosyaları renklendirdiğinden çeviri daha kolay olur. Ayrıca XML dosyanın geçerliliğini de kate'e sınatabilirsiniz. Bazı etiketleri yanlışlıkla silerseniz, depoya hatalı dosya teslim etmekten kurtulabilirsiniz.

Ama siz siz olun buna da fazla güvenmeyin. Çünkü kate DTD ile ilgili hatalara siz zorlamadıkça bakmaz. Son olarak dosyayı teslim etmeden önce doc-tr/doc-base dizininde şu komutunu kullanın:

$ php configure.php --with-lang=tr

Belgenizde kate'in saptayamadığı bir hata varsa bu komut size bilgi verir. Komut hata vermemişse ve bir SVN hesabınız varsa dosyayı depoya gönderebilirsiniz, SVN hesabınız yoksa dosyayı ekip liderine göndermelisiniz. Verdiği hatayı nasıl gidereceğinizi bilmiyorsanız listedekilere sorunuz. (Burada artık esr'nin ünlü belgesinden söz etmeyelim.) Hatalı dosyayı bana gönderebilirsiniz ama ASLA ve ASLA depoya teslim etmeyin. Bunu yaparsanız, site derlenemez ve dilimizi yine desteklenmeyen diller arasında buluruz. Unutmayın sizler bir programlama dilinin belgesini çeviriyorsunuz. Hele SVN hesabı olanlardan böyle hatalar hiç beklenmiyor. Bu bakımdan böyle bir durumun süreklilik kazanması halinde PHP ekibi hakkımızda ne karar verirse haklıdır.

*********************

Aşağıda İngilizce terimlerin bu çeviride kullandığımız Türkçe karşılıkları yazılmıştır. AMACIMIZ AYNI TERİMLERİ KULLANMAK, OKUYUCU FARKLI TERİMLERLE KAVRAM KARGAŞASI İÇİNDE BIRAKMAMAKTIR.
================================================

_               Altçizgi imi
&               Ve imi
Abstract        Metin için "Özet" ifadeler için "soyut" veya "mutlak"
Argument        Değiştirge
Array           Dizi
Associative Array  İlişkisel Dizi
Attribute       Öznitelik
Authentication  Kimlik doğrulama
Authorization   Yetkilendirme
Automatically   Özdevinimli olarak
Backslash       Ters bölü
Binary          Programsa kastedilen "çalıştırılabilir", kendisi bir veri
                türü ise çevrilmez, veri türünü niteliyorsa "ikil", bir
                işleci niteliyorsa "iki terimli".
Bitwise         Bitsel
Boolean         Kendisi veri türü ise çevrilmez. Türü niteliyorsa "mantıksal"
Built-in        Yerleşik
Callback        Geriçağırım
Class           Sınıf
Compile         Derleme
Configuration   Yapılandırma
Constants       Sabitler (Değişmezler değil!)
Control Structure    Denetim Yapısı
Default         Öntanımlı
Detail          Ayrıntı (lütfen "detay" diye çevirmeyin)
Digest          Özet
Directive       Yönerge
double quote    çift tırnak "
Dynamically     Devingen olarak
Escape          Escape tuşu için çevrilmez.
Escape character  Önceleme karakteri
Exception       İstisna
Executable      Çalıştırılabilir
Extention       Eklenti
Float           Gerçek sayı, kayan noktalı sayı
Form            Form
Function        İşlev
Idle            Boşakoşum
Include         dahil etme
Index           (diziler için) indis
Initialize      İlklendirmek
Instantiate     Örnekleme (sınıfın nesnel bir örneğini oluşturma)
Interpreter     Yorumlayıcı
integer         tamsayı
Label           Yafta
Matrix          Dizey
Method          Yöntem
mixed           karışık
Module          Modül
Multithread     Çok evreli
Multibyte       Çok baytlı
Object          Nesne
Operand	        Terim
Operator        İşleç
Original        Özgün
Outputs         Çıktılar
Override        Geçersiz kılmak
Parameter       Değiştirge
Parse error     Çözümleme hatası
Parser          Çözümleyici
Pass into       İçe aktarmak
Pointer         Fare oku sözkonusu ise "imleç", C tarzı ise "gösterici"
Predefined      Önceden tanımlanmış
Procedure       Yordam
Protocol        Protokol
Ouery string    Sorgu dizgesi
Reference       gönderim, atıf yapmak
Regular expression	Düzenli ifade
Resource        Özkaynak
root user       root kullanıcı (Linux'ta en yetkili kullanıcı root'dur).
Runtime         Çalışma anı
Scalar          Sayıl
Scope           Etki Alanı
Serialize       Dizgileştirme
Server          Sunucu
single quote    tek tırnak '
Slash           Bölü imi
Static          Duruk
Statement       Deyim
String          Dizge
Script          Betik
Scripting       Kodlama, kod yazma
Ternary         Üç terimli
Thread          Evre
Tag             İmlenim dilleri (*ML) için "etiket"
Type            "Tür" veya "veri türü"
Unary           Tek terimli
Unserialize     Nesneleştirme
Validation      Geçerlilik
Variable        Değişken
Vector          Yöney
Web Server      HTTP Sunucusu
Widget          Gereç
Version.Revision.Patch   Biz bunun tamamına ve parçalarına sürüm numarası
                diyoruz. Bu kılavuzun okuyucusu için sürüm numarasını oluşturan
                parçaların isimlerinin bir önemi olmayacaktır.
================================================