Japonya pazarına açılan bir finansal teknoloji (FinTech) şirketi, ödeme geçidi API'sini Japoncaya çevirmektedir.
Çevirmen, amount parametresini ve /v1/payments endpoint'ini çevirmeden bırakır, ancak bu parametrenin "kuruş cinsinden işlem tutarını belirttiği" açıklamasını Japoncaya (developer docs standartlarına uygun olarak) kusursuz şekilde aktarır.
API (Application Programming Interface) dokümantasyonu, sistemlerin birbiriyle nasıl iletişim kuracağını, HTTP isteklerini ve dönen yanıt (response) yapılarını bağımsız bir şekilde açıklar.
SDK (Software Development Kit) dokümantasyonu ise, bu API'leri belirli bir programlama dilinde (örneğin Java, Python) daha kolay kullanmak için sunulan hazır kütüphanelerin, fonksiyonların ve kurulum adımlarının çevirisini kapsar.
API evrensel bir sözleşme iken, SDK o sözleşmeyi uygulamaya koyan dile özgü bir alet çantasıdır.
| Özellik | API Dokümantasyonu | SDK Dokümantasyonu |
|---|---|---|
| Odak | İstek/Yanıt formatı, Endpoint, Yetkilendirme | Kurulum, Sınıflar (Classes), Metodlar, Hata Yakalama (Exception) |
| Dil Bağımlılığı | Yok (Genellikle HTTP/REST/GraphQL) | Yüksek (Python, Node.js, Go vb. özelinde) |
| Çeviri Riski | JSON yapılarının ve parametrelerin bozulması | Dile özgü fonksiyon isimlerinin (camelCase vb.) çevrilmesi |
Teknik çevirilerde en sık karşılaşılan hatalar genellikle eksik terminoloji yönetimi ve kod yapılarının ayrıştırılamamasından (parsing) kaynaklanır.
Endpoint'lerin çevrilmesi, JSON anahtarlarının lokalize edilmesi veya kod içi string değerlerinin değiştirilmesi, API'nin çalışmamasına (entegrasyon kırılmalarına) yol açar.
Bu hataların önüne geçmek için önceden tanımlanmış kurallara dayalı "korumalı etiket (protected tag)" sistemleri kullanılmalıdır.
| Hata | Etkisi (Risk) | Doğru Yaklaşım | Mini Örnek |
|---|---|---|---|
| 1. Endpoint'lerin çevrilmesi | 404 Not Found hatası. İstek hedefe ulaşmaz. | Path'ler dokunulmaz kabul edilir. | /kullanici-getir YANLIŞ, /get-user DOĞRU. |
| 2. JSON Key çevirisi | Payload parse edilemez. | Sadece value (değer) çevrilebilir (eğer literal değilse). | "renk": "mavi" YANLIŞ, "color": "mavi" DOĞRU. |
| 3. Parametre isimlerinin çevrilmesi | 400 Bad Request hatası. | Query veya Body parametreleri korunur. | siralama=desc YANLIŞ, sort=desc DOĞRU. |
| 4. Enum değerlerinin çevrilmesi | Veritabanı kayıt veya validasyon hatası. | API'nin beklediği sabit değerler çevrilmez. | Durum: BEKLEYEN YANLIŞ, Durum: PENDING DOĞRU. |
| 5. Header tanımlarının çevrilmesi | Yetkilendirme veya içerik tipi hatası. | Standart ve custom header'lar orijinal bırakılır. | İçerik-Tipi: ... YANLIŞ, Content-Type: ... DOĞRU. |
| 6. Placeholder bozulması | Kodun çalışma zamanında değişkeni bulamaması. | Değişken formatı ({id}, %s) korunmalıdır. |
Merhaba %s DOĞRU, Merhaba % s YANLIŞ. |
| 7. Kod bloklarının lokalize edilmesi | Copy-paste ile çalışan örneklerin kırılması. | <code> veya markdown blokları izole edilir. |
İstek gövdesi tamamen orijinal dilde bırakılır. |
| 8. Boolean değerlerin çevrilmesi | Mantıksal (logic) hatalar. | true/false literal olarak kalmalıdır. | is_active: dogru YANLIŞ, is_active: true DOĞRU. |
| 9. Yorum satırlarında kod referanslarının çevrilmesi | Geliştiricinin referans edilen fonksiyonu bulamaması. | Yorum çevrilse de metod isimleri korunur. | createOrder fonksiyonunu çağırır. DOĞRU. |
| 10. Aşırı resmi/edebi dil kullanımı | Anlaşılırlığın düşmesi (Kötü DX). | Direkt, etken (aktif) ve teknik bir üslup kullanılır. | "Veri sağlanmaktadır" YANLIŞ, "Veriyi döndürür" DOĞRU. |
OpenAPI (eski adıyla Swagger) dokümantasyonları, makine tarafından okunabilen JSON veya YAML formatındaki yapılandırılmış dosyalardır.
Bu dosyaların çevirisinde "single source of truth" (tek doğruluk kaynağı) prensibi esastır; dosyanın teknik iskeleti asla değiştirilmez.
Yalnızca insanların okuması için tasarlanmış summary, description ve uyarı mesajı (error message) alanları CAT (Bilgisayar Destekli Çeviri) araçları yardımıyla güvenli bir şekilde filtrelenip çevrilir.
Teknik çeviri projelerinde terimce (glossary) ve stil rehberi (style guide) kullanımı, marka sesinin ve teknik doğruluğun korunması için vazgeçilmezdir.
Style guide; aktif/pasif ses kullanımını, tarih/saat formatlarını ve hitap şeklini belirlerken; glossary, ürüne özgü fonksiyon adlarının veya sektörel terimlerin dilden dile nasıl aktarılacağını standartlaştırır.
Bu araçlar, geliştirici kitlesinin bilişsel yükünü azaltır.
| İngilizce Terim | Hedef Türkçe Terim | Kural / Not (Style Guide) |
|---|---|---|
| Deploy | Dağıtmak (veya Deploy etmek) | Şirket tercihine göre belirlenir, metin boyunca sabit kalır. |
| Fetch | Getirmek | "Çekmek" kullanılmamalıdır, veri okuma işlemi kast edilir. |
| Dashboard | Kontrol Paneli | Arayüz çevirisi ile tutarlı olmalıdır. |
| Token | Token | Çevrilmez, olduğu gibi bırakılır ("Jeton" kullanılmaz). |
Yazılım Geliştirme Yaşam Döngüsünde (SDLC) ürünler sürekli güncellenir.
"Fark (Diff) Çevirisi" (veya teknik adıyla artımlı çeviri), bir API dokümantasyonu veya sürüm notu (release notes) güncellendiğinde, tüm metni baştan çevirmek yerine yalnızca değişen, eklenen veya silinen satırların (diff) tespit edilip çevrilmesi işlemidir.
Bu yöntem, Çeviri Belleği (Translation Memory - TM) kullanılarak maliyetleri düşürür ve pazara çıkış süresini (Time-to-Market) hızlandırır.
Modern DevRel ve dokümantasyon süreçlerinde çeviri yönetimi, yazılım kodunun yönetildiği sistemlerle aynı yerde gerçekleşir.
Sürekli Lokalizasyon (Continuous Localization), dokümantasyon dosyalarının (Markdown, MDX, RST) barındırıldığı Git depolarına (GitHub, GitLab) doğrudan entegre edilen Pull Request (PR) akışlarıyla sağlanır.
Geliştirici ana dilde bir değişiklik commit ettiğinde, lokalizasyon platformunda otomatik bir çeviri görevi tetiklenir ve çeviri bittiğinde otomatik bir PR açılır.
Profesyonel bir API/SDK dokümantasyon çevirisi hizmetinin teslimatı, salt çevrilmiş metin dosyalarından daha fazlasını içermelidir.
BOFU (Bottom of the Funnel) aşamasındaki karar vericiler için hizmet kapsamı; dilsel kalite güvencesi (LQA), teknik bütünlük kontrolleri ve sürekli entegrasyona hazır formatta dosya teslimi sunarak operasyonel riski sıfıra indirmeyi hedefler.
C: Hayır. Kod blokları, geliştiricilerin doğrudan kopyalayıp kullanabilmesi için orijinal dilinde (genellikle İngilizce) ve işlevsel formatında bırakılır. Çevrilmesi durumunda kod çalışmaz (syntax error). Sadece kod içindeki geliştiriciye not bırakan yorum satırları çevrilebilir.
C: Evet, doğru araçlarla yönetildiğinde güvenlidir. OpenAPI dosyalarındaki paths, parameters gibi teknik yapılar izole edilerek, sadece kullanıcıya dönük açıklamalar (description, summary) lokalize edilir. Böylece dosyanın makine tarafından okunabilirliği bozulmaz.
C: Fark (diff) çevirisi, bir dokümanın yeni versiyonu yayınlandığında tüm metni baştan çevirmek yerine sadece değişen veya eklenen kısımların tespit edilerek çevrilmesidir. Sürekli güncellenen SDK'larda Çeviri Belleği (TM) kullanılarak sadece yeni kısımların (artımlı güncellemelerin) çevrilmesi, zaman ve operasyonel maliyet tasarrufu sağlar.
C: Çevrilen metinlerin, hedef dildeki ortalama genleşme oranları nedeniyle UI ekranlarında taşıp taşmadığını veya arayüzü bozup bozmadığını görmek için yapılır. Çeviri başlamadan önce potansiyel tasarım hatalarını erken aşamada tespit eder.
C: Fiyatlandırma temel olarak kelime sayısına dayanır; ancak tekrar oranları (Çeviri Belleği analizleri), format karmaşıklığı (JSON, YAML, Markdown ayrıştırma işlemleri) ve hedeflenen LQA (dil kalite güvencesi) adımları toplam proje maliyetini etkiler.
C: Dokümanların barındırıldığı GitHub/GitLab gibi repolar, lokalizasyon yönetim sistemlerine (TMS) webhook'lar aracılığıyla bağlanır. Kod deposuna yapılan bir değişiklik lokalizasyonu tetikler, çeviri bittiğinde sisteme otomatik bir Pull Request (PR) açılır.
C: "Fetch", "Deploy", "Commit" gibi teknik kelimelerin ürün genelinde, hedef dilde hep aynı karşılıklarla (tutarlı) kullanılmasını sağlar. Bu durum, geliştiricilerin dokümanı okurken zihinsel karmaşa yaşamasını engeller.
C: Parametre adlarının, endpoint yollarının veya JSON anahtarlarının yanlışlıkla çevrilmesi durumunda API istekleri başarısız olur (örn: 400 veya 404 hataları). Bu, geliştiricilerin ürünü entegre edememesine ve destek maliyetlerinin artmasına yol açar.
Süreci güvenle başlatmak için aşağıdaki 6 maddelik eylem planını uygulayabilirsiniz:
Copyright © Universal bir Unigroup şirketidir. Tüm Hakları Saklıdır. Sitede yer alan içerikler tümü ile Universal Dil Hizmetleri ve Yayıncılık'a ait ve tarih itibariyle tescillidir. Universal'in izni olmadan kısmi ya da tümü ile kullanılması yasaktır. Aksinin tespit edilmesi durumunda hukuki işlem uygulanacaktır