Kodları Bozmadan Teknik Belgeleri Nasıl Çevirilir

TABLE OF CONTENTS

Teknik belgeler affetmez: tek bir bozuk kod çiti, yer tutucu veya bağlantı yapıları bozabilir, okuyucuları şaşırtabilir veya kopyala-yapıştır hatalarına neden olabilir. Bu kılavuz, kodu sağlam ve belgeleri gönderilebilir halde tutarken, teknik belgeleri güvenle çevirmek için tekrarlanabilir, güvenli bir iş akışı sunar.

Kimler için: geliştirici belgeleri, API kılavuzları ve README tarzı içerikler üzerinde çalışan teknik yazarlar, geliştirici savunucuları ve çevirmenler.

Genel bakış:

Asla çevrilmemesi gerekenleri anlayın (kod, anahtarlar, belirteçler)
Araçların ayrıştırdığı sözdizimini koruyun (çitler, süslü parantezler, bağlantılar)
Düzenlemelerden sonra yapılandırılmış verileri ve bağlantıları doğrulayın
Sorunları sürümden önce yakalamak için otomasyonu kullanın

Çeviri Öncesi Hazırlık

İçerik türlerini envanterleyin

Markdown (başlıklar, bağlantılar, tablolar), kod blokları, satır içi kod
Yapılandırılmış veriler: JSON/YAML/TOML parçacıkları ve yapılandırma dosyaları
Ekran görüntüleri, diyagramlar ve gömülü görseller

Çevrilemez belirteçleri tanımlayın

Dosya yolları, paket adları, ithalatlar, API adları, CLI bayrakları, çevre değişkenleri
Yer tutucular ve değişkenler: {count}, %s, $HOME, {{token}}
Dosya adları ve uzantıları: config.yaml, .env, .md, .json

Tutarlılık kılavuzlarını oluşturun

Alan terimleri ve ürün adları için sözlük/terim tabanı
Stil kılavuzu: ton, resmiyet, noktalama, büyük harf kullanımı, başlık kuralları
Yerel dil başına bağlantı/slug stratejisi (kararlı vs yerelleştirilmiş)

Güvenli doğrulama ayarlayın

Her partiden sonra Markdown/bağlantıları doğrulamak için hazırlık yapısı
JSON/YAML/TOML için ayrıştırıcılar/linterlar
CI’da bağlantı denetleyici ve bağlantı doğrulayıcı

Temel Güvenlik Önlemleri

Kod, tanımlayıcılar, anahtarlar, dosya adları, çevre değişkenleri veya bayrakları çevirmeyin.
Araçların ayrıştırdığı noktalama işaretlerini ve sözdizimini koruyun (ters tırnaklar, süslü parantezler, borular).
Önemli boşlukları koruyun: kod ve liste yapısı için girinti.
Dil etiketi ile birlikte çitli kod bloklarını tutarlı bir şekilde kullanın (js, bash, vb.).
Çevirmen notlarını “kod mantığını düzeltmek” yerine tercih edin—sorunları bakıcılara bildirin.

Kod Blokları ve Satır İçi Kod

Kod çitlerini, dil ipuçlarını ve içeriği olduğu gibi koruyun. Yalnızca yorumları ve gerekirse insan tarafından okunabilir dizeleri çevirin.

Örnek—güvenli vs güvensiz:

// GÜVENLİ: Yalnızca yorum yerelleştirilmiştir
// Bir kullanıcı belirteci alır
import { getToken } from "@acme/sdk";
const token = await getToken();

// GÜVENSİZ: Tanımlayıcıları/içe aktarmaları/paket adlarını çevirmeyin
// import { obtenirJeton } from "@acme/sdk"; // ❌

Satır içi kod olduğu gibi kalmalıdır:

İyi: “npm install -g acme-cli çalıştırın ve ardından acme login yapın.”
Kötü: “npm install -g acme-cli çalıştırın ve ardından acme connexion yapın.” ❌

Kopyala-yapıştırabilirliği doğrulayın: Bir okuyucu herhangi bir kod parçasını kopyalarsa, kaynakta olduğu gibi çalışmalıdır.

Yer Tutucular ve ICU Mesaj Formatı

Yer tutucuları tam olarak, etraflarındaki boşluklar ve noktalama işaretleri dahil koruyun.

# Jetonları veya boşlukları değiştirmeyin
echo "Processing {count} files"   # ✅
echo "Processing { count } files" # ❌ süslü parantezlerin içine boşluk ekler

ICU örneği:

{count, plural,
  =0 {Mesaj yok}
  one {# mesaj}
  other {# mesajlar}
}

Anahtarları değiştirmeyin (count, one, other).
Yalnızca insan tarafından okunabilir kısımları çevirin (“mesaj”, “mesajlar”).
Ürün rehberliği olmadan çoğul kategorileri eklemeyin veya çıkarmayın.

Bağlantılar, Çapalar ve Sluglar

Markdown bağlantı sözdizimini ve çözümleme stratejisini tutarlı tutun.

[API kılavuzunu okuyun](/api/getting-started)  
[Yapılandırma bölümüne bakın](#configuration)

Gerekirse bağlantı metnini çevirin; URL’ler ve çapalar konusunda dikkatli olun.
Çapalar: ya yerel çapaları tüm yerellerde sabit tutun ya da her yerel için çapalar oluşturun ve referansları buna göre güncelleyin.
Çeviri sonrası göreceli yolların ve karma çapaların hala çözüldüğünü doğrulayın.
Dosya uzantılarını veya sorgu parametrelerini çevirmeyin.

Yapılandırılmış Veri (JSON/YAML/TOML)

Yalnızca değerleri çevirin—anahtarları, türleri veya yapıyı asla. Düzenlemeden sonra her zaman yeniden ayrıştırın.

JSON:

{
  "title": "Kullanıcı Kılavuzu",
  "cta": "Başlayın",
  "limits": { "max": 5, "unit": "istek/saniye" }
}

title, cta, limits, max gibi anahtarlar değişmeden kalmalıdır.
Sayılar, booleans ve null’lar kelime olarak değil, tür olarak kalmalıdır.

YAML (katlanmış skalarlar):

note: >
  Satırlar tek bir paragraf olarak katlanır.
  Girintiyi ve işaretçileri koruyun.

Tırnak işaretlerini, kaçış karakterlerini, girintiyi ve son virgülleri (uygulanabilir olduğunda) koruyun.

Dosya Adları, CLI ve API İsimleri

Dosya adlarını, paket adlarını, uç noktaları veya CLI bayraklarını çevirmeyin.
Büyük/küçük harf duyarlılığını kaynakta olduğu gibi koruyun (örneğin, --DryRun ve --dry-run).
Komutları kelimesi kelimesine koruyun; yerel farklılıklar varsa açıklamalar ekleyin.

# Doğru
kubectl get pods --namespace default

# Yanlış (bayrak çevrilmiş) ❌
kubectl get pods --nom-espace defaut

Markdown Dikkat Edilmesi Gerekenler

Tablolar: boruları ve hizalamayı koruyun; sütunları bölmeyin.

| Seçenek | Açıklama             |
|--------:|----------------------|
|   -v    | Ayrıntılı çıktı      |
|   -q    | Sessiz mod           |

Uyarılar/notlar: aracınız tarafından kullanılan işaretçileri koruyun.
Satır içi HTML: etiketlere/özelliklere dokunmaktan kaçının.
Dipnotlar: kimlikleri ve sıralamayı koruyun.
Akıllı tırnaklar: kod bağlamlarında düz tırnakları tercih edin.

Görseller ve Erişilebilirlik

Anlam için alternatif metni yerelleştirin, piksel içeriği için değil.
Yerel dil içermeyen ekran görüntülerini tercih edin (UI’yi vurgulayın, dili değil) veya yerel setler sağlayın.
Diyagram kaynak dosyalarını (örneğin, Mermaid) yereller arasında senkronize tutun.
Görsellerde gömülü metinden kaçının; altyazıları ve etiketleri dışsallaştırın.

SEO ve Metadata

Başlıkları, açıklamaları ve başlıkları yerel uygun anahtar kelimelerle çevirin.
Kanonik URL’leri ve hreflang’ı site kurallarıyla tutarlı tutun.
Meta/özellik anahtarlarını veya JSON‑LD anahtarlarını çevirmeyin.
404 hatalarından kaçınmak için slug’ları bağlantı stratejinizle hizalayın.

İş Akışı ve Otomasyon

Kod parçalarını ve etiketleri koruyan bir CAT/LLM iş akışı kullanın.
Terminolojiyi bir sözlük ve çevrilmemesi gerekenler listesi ile kilitleyin.
Markdown’ı kontrol etmek ve JSON/YAML’ı doğrulamak için ön taahhüt kancaları ekleyin.
Her PR’de bir bağlantı kontrolü ve çapa doğrulayıcı çalıştırın.
Değişiklikleri küçük, gözden geçirilebilir parçalar halinde toplu olarak yapın ve farklılıkları takip edin.

Önerilen araçlar (yığınınıza uyarlayın):

CI’de Markdown kontrolü ve bağlantı kontrolü
Sözdizimi gerilemelerini yakalamak için JSON/YAML ayrıştırma adımı
Yer tutucuları ve sayısal formatları taramak için Regex paketleri

QA ve Doğrulama

Birleştirmeden önce bu kontrolleri çalıştırın:

Sözdizimi sorunlarını yakalamak için siteyi oluşturun: pnpm build
Tür/içerik kontrolleri (Astro içerik koleksiyonları): pnpm astro check
Anahtar sayfaları önizleyin ve spot test yapın: pnpm preview
Kod örneklerinin derlenip çalıştığını doğrulayın (uygulanabilir olduğunda)
Bir bağlantı ve çapa kontrolü çalıştırın; herhangi bir 404 veya kırık hash’i düzeltin

Yaygın Tuzaklar

Anahtarları/yer tutucuları yanlışlıkla çevirmek.
Kod çitlerini veya tablo borularını kırmak.
Dosya yollarını, bayrakları veya API adlarını yerelleştirmek.
Çapa bağlantılarını güncellemeden başlıkları değiştirmek.
Kod veya JSON içinde akıllı tırnaklar eklemek.

Ek: Hızlı Kontrol Listeleri

Uçuş öncesi (5 öğe)

Sözlük ve çevrilmemesi gerekenler listesi hazır
Jetonlar/yer tutucular tanımlanmış ve korunmuş
Çapa/slug stratejisi onaylanmış
Bağlantı hedefleri eşlenmiş (iç vs dış)
Hazırlık yapısı mevcut

Kod örneği güvenliği (5 öğe)

Çitler ve dil ipuçları sağlam
Tanımlayıcılar/ithalatlar dokunulmamış; yorumlar sadece yerelleştirilmiş
Yer tutucular ve alıntılar korunmuş
Kopyala-yapıştır testi geçiyor
Güncellenmemiş parçalar bakımcılara işaretlenmiş

Yapılandırılmış veri (5 öğe)

Anahtarlar ve türler dokunulmamış
Alıntılar/kaçışlar/sekme korunmuş
Sayılar ve boole türleri olarak kalıyor
Ayrıştırıcı/linter yerel olarak geçiyor
Yanlışlıkla anahtar değişiklikleri için farklılıklar gözden geçirilmiş

İlgili okuma