PHP Belgelerini NASIL çevrilir?
PHP Belgelelerinin yapısı ve daha pek çok şey hakkında fikir edinmek için
http://wiki.php.net/doc/scratchpad/howto#quick_guide_for_improving_the_existing_php_documentation
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:
http://ceviri.belgeler.gen.tr/php/sondurum.html
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 ' kullanılmışsa siz de onu kullanın. Sizin cümle
içinde tek tırnak imi kullanmanız gerekirse zor gelmeyecekse yine ' 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ı (' olur, kendileri) görüntülenmez. Yani ' 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.
================================================