Yazılım API Dokümantasyonu Çevirisinde Ölçü Birimleri ve Semboller

API dokümantasyonu çevirisinde ölçü birimleri ve semboller, yalnızca metnin bir parçası değildir; geliştiricinin bir isteği nasıl göndereceğini, yanıtı nasıl yorumlayacağını ve bir değeri hangi formatta kullanacağını belirler. Bu nedenle API dokümantasyonu çevirisi yapılırken birimlerin, sembollerin, sayıların ve kod içindeki gösterimlerin anlamı korunmalıdır. Bir noktanın virgüle çevrilmesi, birim sembolünün yanlış yorumlanması veya bir parametrenin biçiminin değiştirilmesi, dokümanı okuyan kişinin uygulamasında hataya yol açabilir.

Bu yazıda uzunluk, zaman, veri boyutu, sıcaklık ve oran gibi değerlerin nasıl ele alınması gerektiğini; sembol, sayı ve kod bloklarının hangi durumlarda çevrilmemesi gerektiğini açıklıyoruz. Amaç, Türkçe okuyucuya daha anlaşılır bir doküman sunarken API’nin teknik davranışını değiştirmemektir.

API dokümantasyonu çevirisi neden ölçü birimlerine özel dikkat gerektirir?#

API belgelerinde ölçü birimleri genellikle parametre açıklamalarında, örnek isteklerde, yanıt gövdelerinde, hata mesajlarında ve tablo içeriklerinde görülür. Bir değerin yanında yer alan birim, geliştiriciye bu değerin nasıl üretileceğini veya yorumlanacağını söyler. Örneğin bir alanın milisaniye cinsinden süre beklediği belirtiliyorsa, bu bilgi saniye olarak çevrilmemeli ya da okuyucunun varsayımına bırakılmamalıdır.

Teknik çeviride temel yaklaşım, birimin kaynak metindeki işlevini korumaktır. Açıklama cümlesi Türkçeleştirilebilir; ancak API’nin kabul ettiği değer, parametre adı ve kod örneğindeki teknik gösterim aynı kalmalıdır. Birim açıklaması yerelleştirilirken kaynakta kullanılan sistemin değiştirilip değiştirilmediği açıkça değerlendirilmelidir.

• Parametrenin hangi birimde değer aldığı belirlenmelidir.
• Birim sembolü ile birimin açık adı birbiriyle tutarlı kullanılmalıdır.
• Kaynak dokümanda açıkça belirtilmeyen bir dönüşüm yapılmamalıdır.
• Örnek kod, JSON, XML, YAML ve tablo değerleri çeviri sırasında korunmalıdır.
• Aynı birim, dokümanın tamamında aynı yazım biçimiyle kullanılmalıdır.

Çeviride hangi ölçü birimleri ve teknik değerler kontrol edilmelidir?#

API dokümantasyonu yalnızca fiziksel ölçülerden oluşmaz. Yazılım belgelerinde süre, veri miktarı, oran, açı, koordinat ve kapasite gibi farklı değer türleri bulunabilir. Her değer türü, teknik bağlamına göre incelenmelidir.

Zaman ve süre birimleri#

Milisaniye, saniye, dakika ve saat gibi zaman birimleri API belgelerinde sıkça kullanılır. Özellikle zaman aşımı, önbellek süresi, yanıt süresi ve zaman damgası açıklamalarında birimin hangi değerle ilişkili olduğu net olmalıdır. “timeout: 5000” örneğinde açıklama, değerin beş bin saniye mi yoksa beş bin milisaniye mi olduğunu belirleyecek şekilde aktarılmalıdır.

“ms”, “s”, “min” ve “h” gibi kısaltmaların yazımı kaynak dokümandaki teknik standarda göre korunabilir. Ancak açık metinde Türkçe karşılığı veriliyorsa sembol ile açıklama arasında çelişki oluşmamalıdır. Zaman damgalarında ise saniye veya milisaniye bilgisi, yalnızca metnin anlamı değil veri işleme biçimi açısından da önem taşır.

Veri boyutu ve kapasite değerleri#

Bayt, kilobayt, megabayt ve gigabayt gibi veri boyutu ifadeleri; dosya yükleme sınırı, yanıt gövdesi, kota veya depolama alanı açıklamalarında kullanılabilir. “KB” ve “KiB” aynı anlamda değerlendirilmemelidir. Kaynak metin bu ayrımı yapıyorsa çeviride de korunmalıdır. Bir dosya boyutu ifadesini daha anlaşılır kılmak amacıyla farklı birime dönüştürmek, API’nin gerçek sınırını değiştirebilir.

Benzer şekilde “bit” ve “byte” ayrımı da dikkatle ele alınmalıdır. Türkçe açıklamada “bit” ve “bayt” karşılıkları kullanılabilir; fakat kod içindeki alan adları, sabitler ve örnek değerler değiştirilmemelidir. Dokümanın başında birim kullanımına ilişkin kısa bir açıklama bulunuyorsa bu bölüm, sonraki örneklerle karşılaştırılarak kontrol edilmelidir.

Oran, yüzde ve ondalık değerler#

Yüzde işareti, oran ifadeleri ve ondalık sayılar API belgelerinde indirim, başarı oranı, kullanım seviyesi, güven skoru veya ağırlık gibi alanlarda yer alabilir. Türkçede ondalık ayırıcı olarak virgül kullanılması doğal olsa da JSON ve bazı programlama dillerinde nokta kullanımı zorunlu olabilir. Bu nedenle açıklama metnindeki sayı ile kod örneğindeki sayı aynı biçimde ele alınmamalıdır.

Örneğin açıklamada “0,75 oranı” ifadesi kullanılabilir; ancak JSON içindeki sayısal değer, kaynak formatın gerektirdiği şekilde korunmalıdır. Yüzde işaretinin sayıdan önce veya sonra yazılması da teknik metnin bağlamına göre değerlendirilmelidir.

Ölçü birimi sembolleri nasıl korunmalı?#

Semboller, çeviri sırasında en kolay gözden kaçan unsurlardan biridir. “°”, “%”, “/”, “-”, “_”, “>”, “<”, “+” ve “#” gibi işaretler bir değerin anlamını, koşulunu veya parametre yapısını etkileyebilir. Bu işaretlerden bazıları normal metin içinde, bazıları ise kod veya komut yapısı içinde bulunur.

Ölçü birimi sembolü ile matematiksel veya programlama sembolünü birbirinden ayırmak gerekir. Örneğin “/s” bir hız veya saniye başına değer ifade edebilirken URL, dosya yolu ya da kod içinde farklı bir işlev taşıyabilir. Çevirmen, sembolü yalnızca görsel bir karakter olarak değil, bulunduğu yapının parçası olarak incelemelidir.

• Derece işareti ile sıcaklık veya açı ifadesinin ilişkisi kontrol edilmelidir.
• Yüzde işareti, oran açıklamasıyla aynı değeri göstermelidir.
• Eksi işareti ile kısa çizgi birbirinin yerine kullanılmamalıdır.
• Alt çizgi, tire ve nokta içeren parametre adları değiştirilmemelidir.
• Büyüktür, küçüktür ve eşittir sembolleri koşul ifadelerinde korunmalıdır.
• Birim sembolündeki büyük-küçük harf farkı göz ardı edilmemelidir.

Kod, örnek istek ve yanıt gövdelerinde birim kontrolü#

API çevirisinin en kritik bölümlerinden biri kod örnekleridir. Kod içinde yer alan alan adları, endpoint adresleri, HTTP metotları, başlıklar, anahtarlar, değerler ve semboller çoğu zaman çevrilmez. Çevirmen burada açıklama ile çalışır; çalıştırılabilir yapıyı bozmamaya dikkat eder.

Bir örnek istekte “limit”, “offset”, “duration” veya “timestamp” gibi alanlar yer alıyorsa, açıklama metnindeki karşılıkları çevrilebilir; ancak örnek gövdesindeki anahtar adları korunmalıdır. Aynı şekilde yanıt örneğinde sayısal değerler bulunuyorsa bunlara binlik ayırıcı eklenmemeli, ondalık ayırıcı değiştirilmemeli ve değerlerin başına veya sonuna açıklama amaçlı sembol konulmamalıdır.

Markdown tabloları, kod blokları ve satır içi kod ifadeleri de ayrıca kontrol edilmelidir. Birim açıklaması tablo hücresindeyse sütun başlığı ile satır değerlerinin birbirine uygun olup olmadığı incelenmelidir. Kod bloğunda açıklama satırları bulunuyorsa yalnızca doğal dil bölümü çevrilmeli, komutun kendisi korunmalıdır.

Sayı biçimi ile veri biçimini ayırmak#

Türkçe metinlerde binlik ayırıcı ve ondalık ayırıcı kullanımı, teknik veri formatlarından farklı olabilir. Bu farkın en önemli olduğu yerler JSON, XML, CSV ve benzeri yapılardır. Bir sayının okunabilirliğini artırmak amacıyla teknik veri içine nokta, virgül veya boşluk eklemek doğru değildir.

Çeviri kontrolünde şu sorular sorulmalıdır: Değer bir sayı mı, metin mi? API bu değeri hangi formatta bekliyor? Birim açıklama içinde mi, alan adında mı, yoksa örnek değerin yanında mı? Bu soruların yanıtı, yerelleştirme yapılacak alanı belirlemeye yardımcı olur.

Yerelleştirme ile teknik doğruluk nasıl dengelenir?#

İyi bir API dokümantasyonu çevirisi, Türkçe okuyucu için anlaşılır olmalı; ancak geliştiricinin API’yi kullanma biçimini değiştirmemelidir. Bunun için açıklama metni, başlıklar ve uyarılar doğal Türkçeyle çevrilirken teknik kimliği olan unsurlar korunur.

Örneğin “request body”, “response”, “header” ve “query parameter” gibi terimlerin Türkçe karşılıkları kullanılabilir. Fakat belirli bir kütüphane, ürün, endpoint veya parametre adı kaynakta nasıl geçiyorsa öyle bırakılmalıdır. Terimlerin belgede tutarlı kullanılması, ölçü birimleri kadar önemlidir. Bu konuda yazılım API dokümantasyonu çevirisinde terminoloji sözlüğü hazırlama yaklaşımı yararlı bir referans oluşturur.

Yerelleştirme kararı verilirken şu ayrım yapılabilir:

Çeviri sonrası ölçü ve sembol kontrol listesi#

Son okuma aşamasında yalnızca yazım ve dil bilgisi kontrolü yapmak yeterli değildir. Ölçü birimleri ve semboller için ayrı bir teknik kontrol listesi hazırlanmalıdır. Bu liste, dokümanın farklı bölümlerinde aynı değerin farklı yazılmasını önler.

1. Kaynak dosyadaki tüm birim ve semboller belirlenir.
2. Aynı birimin başlık, açıklama, tablo ve örnek kodlarda nasıl kullanıldığı karşılaştırılır.
3. Sayıların basamakları, işaretleri ve ondalık gösterimleri kontrol edilir.
4. Parametre adları ve JSON anahtarlarının değişmediği doğrulanır.
5. Ölçü biriminin açıklama ile örnek değer arasında uyumlu olduğu incelenir.
6. Kod bloklarına yanlışlıkla çeviri, noktalama veya biçimlendirme eklenmediği kontrol edilir.
7. Güncellenmiş sürüm ile önceki sürüm arasında birim veya sembol farkı olup olmadığı karşılaştırılır.

Bu yaklaşım, teknik dokümanlarda sık görülen küçük ama etkili hataları azaltır. Benzer bir kontrol mantığı, birim ve sembol kontrolü gerektiren farklı teknik belgelerde de uygulanabilir. Ayrıca revizyonların izlenmesi gereken projelerde, değişen parametre ve örneklerin ayrı olarak işaretlenmesi yararlı olur.

API dokümantasyonu çevirisinde teslim öncesi dikkat edilmesi gerekenler#

Dokümanın formatı da teknik doğruluğun bir parçasıdır. Başlık seviyeleri, tablolar, kod blokları, bağlantılar ve uyarı kutuları kaynak metindeki işlevini korumalıdır. Bir sembolün yazı tipi, üst simge veya alt simge olarak gösterilmesi anlam taşıyorsa biçimlendirme de kontrol edilmelidir.

Dosyada birden fazla dil veya bölgeye göre sayı biçimi kullanılıyorsa hangi bölümün çevrildiği netleştirilmelidir. Aynı API belgesinin farklı sürümleri bulunuyorsa çevirinin doğru sürüm üzerinden yapıldığından emin olunmalıdır. Aksi durumda birim ve sembol kontrolü doğru yapılsa bile doküman güncel olmayan parametreleri içerebilir.

Resmî kullanım amacı bulunan teknik belgelerde, çevirinin yeminli yazılı tercüme, noter onay süreci desteği veya apostil süreci desteği gerektirip gerektirmediği ayrıca sorulabilir. Bu ihtiyaç, belgenin kullanılacağı kuruma ve işlem türüne göre değişebilir; bu nedenle önceden netleştirilmesi gerekir. API dokümantasyonunun teknik içeriği içinse asıl odak, kodun ve veri biçiminin bozulmadan aktarılmasıdır.

Antalya’da yazılım dokümanı çevirisi için çalışma yaklaşımı#

Antalya merkezli Pura Tercüme, teknik içeriklerin Türkçeye veya farklı dillere aktarılmasında belgenin kullanım amacının ve formatının önceden değerlendirilmesine önem verir. Antalya ve ilçelerinde yazılım, teknoloji veya teknik dokümantasyonla çalışan kişiler; çevrilecek dosyanın yanı sıra varsa terim listelerini, sürüm bilgilerini ve korunması gereken kod alanlarını paylaşarak sürecin daha sağlıklı ilerlemesine katkı sağlayabilir.

Dokümanın yalnızca açıklama bölümlerinden mi, yoksa tablo, örnek istek, yanıt gövdesi ve hata mesajlarından mı oluştuğu belirtilmelidir. Böylece ölçü birimleri, semboller ve teknik ifadeler için uygun bir kontrol kapsamı oluşturulabilir. Pura Tercüme; yeminli yazılı tercüme, noter onay süreci desteği, apostil süreci desteği, sözlü tercüme ve dijital/kargo teslim seçenekleri sunar. İhtiyacınızın kapsamını öğrenmek için iletişim kanallarından bilgi paylaşabilirsiniz.

Sonuç: API dokümantasyonu çevirisinde birim ve sembol standardı#

API dokümantasyonu çevirisi sırasında ölçü birimleri ve semboller, metinden bağımsız teknik veriler olarak ele alınmalıdır. Zaman birimleri, veri boyutları, yüzde değerleri, ondalık sayılar, parametre adları ve kod örnekleri aynı kontrol sürecinden geçirilmelidir. Açıklamalar anlaşılır Türkçeyle çevrilirken API’nin beklediği format korunmalıdır.

Başarılı bir sonuç için çeviri öncesi kapsam belirleme, tutarlı terminoloji kullanımı, kod ve tablo kontrolü, sürüm karşılaştırması ve teslim öncesi son okuma birlikte yürütülmelidir. Teknik belgenizi paylaşmadan önce hangi bölümlerin çevrileceğini ve hangi sembollerin aynen korunacağını belirtmeniz, beklentilerin doğru anlaşılmasına yardımcı olur. Pura Tercüme ile iletişime geçerek dokümanınızın kapsamı hakkında bilgi alabilirsiniz.

Sık Sorulan Sorular#

API dokümantasyonu çevirisinde ölçü birimleri çevrilir mi?#

Açıklama metnindeki birim adları Türkçeleştirilebilir; ancak API’nin kullandığı semboller, parametreler ve veri formatları kaynak teknik yapıyı bozmayacak şekilde korunmalıdır.

JSON içindeki ondalık sayılarda virgül kullanılabilir mi?#

JSON ve benzeri teknik formatlarda kaynak yapının gerektirdiği sayı gösterimi korunmalıdır. Türkçe metindeki virgül kullanımı, teknik veri içine doğrudan aktarılmamalıdır.

API parametre adları tercüme edilir mi?#

Parametre adları, endpoint’ler ve kod içindeki anahtarlar genellikle çevrilmez. Açıklama bölümü Türkçeleştirilirken teknik adların yazımı aynen korunur.

API dokümantasyonu için noter veya apostil gerekir mi?#

Bu ihtiyaç belgenin kullanılacağı işlem ve kuruma göre değişir. Gerekli olup olmadığını ilgili kurumdan öğrenebilir, çeviri süreci için Pura Tercüme’den bilgi alabilirsiniz.