API üzerinden dize kataloğu yerelleştirme

Transept’in anahtarlı formatı .tstrings.json'dur: Her biri sabit bir id, bir source ve isteğe bağlı olarak bir context (dizenin ne olduğu, nerede göründüğü), bir max_length ve placeholders içeren bir birimler listesidir. ID bir sözleşme niteliğindedir: Çevirilerin tekrar içe aktarmalar boyunca kimliğini koruması, inceleme durumunun kalıcılığı ve dışa aktarma sırasında her dilin anahtarlanması bu sayede gerçekleşir. Bu ek özelliklerin her ikisi de somut işlevlere sahiptir: Bağlam, çevirmen kılavuzu olarak modele ulaşır; karakter sınırı ise otomatik bir 'kısalt ve tekrar dene' işlemiyle uygulanır.

CSV, gettext PO ve XLIFF dosyaları, uygulama veya yükleme uç noktası üzerinden aynı anahtarlı birimler olarak içe aktarılır; hangi formatın neye karşılık geldiğini görmek için dize dosyaları sayfasına bakabilirsiniz. Bu makale, .tstrings.json dosyasının yerel yapı olduğu durumlarda, bu döngüyü kod üzerinden yönetmek üzerinedir.

Kataloğu JSON olarak içeren bir POST /documents/import-strings isteği gönderin. Hedef diller sabit bir sırayla belirlenir: İstekteki açık target_language / target_languages parametresi önceliklidir; aksi takdirde katalog başlığındaki target_locales kullanılır; o da yoksa, çağrı hedefsiz bir belgeyi içe aktarmak yerine anında no_target_languages hatasıyla başarısız olur. Çağrı bir processing_job_id döndürür; içe aktarma tamamlanana ve belge kimliklerini (ID) alana kadar GET /document-jobs/{id} uç noktasını sorgulayın.

Dosyanın halihazırda içerdiği çeviriler (targets: {de: "…"}), her dizenin aktif çevirisi olarak atanır; bu işlem ücretsizdir, herhangi bir çalıştırma (run) gerektirmez ve çeviri belleğinizi anında besler. Bu, uygulama üzerinden mevcut çevirileri getirme işlemiyle aynı şekilde çalışır.

# BASE="https://app.transept.ai/api/public/v1"; KEY from Settings → Developer
curl -s -X POST $BASE/documents/import-strings \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"document": {
        "format": "transept-strings", "version": 1, "source_locale": "en",
        "target_locales": ["de", "fr", "uk"],
        "metadata": {"name": "App UI"},
        "units": [
          {"id": "app.save", "source": "Save", "context": "Toolbar button"},
          {"id": "app.greeting", "source": "Welcome, {name}", "context": "Dashboard header"}
        ]}}'
# → { processing_job_id }; poll GET /document-jobs/{id}

POST /documents/{id}/import-strings uç noktasına kırpılmış bir dosya değil, mevcut kataloğun tamamını tekrar gönderin. Sunucu bunu birim kimliğine göre karşılaştırır ve bulduğu sonuçları (added, changed, unchanged, removed) ve her dil sürümü için işlem gerektiren tam bloklar olan delta_block_ids değerini döndürür. Bu nesneyi bir toplu çalıştırmanın block_ids parametresi olarak olduğu gibi aktardığınızda yalnızca o bloklar çevrilir; ayrıca, delta'yı aynı çağrıda işlemek için tekrar içe aktarma sırasında run parametresini satır içi olarak da geçebilirsiniz.

Değişmeyen birimler çevirilerini ve üzerlerinde yapılmış olan tüm incelemeleri korur; bu, Sadece değişenleri çalıştır özelliğinin API tarafındaki karşılığıdır. Yüzlerce dizelik bir katalogda tek bir dizeyi düzeltmek, size yalnızca bir dizeye mal olur.

# 1. Re-submit the whole current catalog; the server diffs it by unit id
curl -s -X POST $BASE/documents/<master>/import-strings \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d @app-ui.tstrings.json
# → { units: {added, changed, unchanged, removed}, delta_block_ids: {<doc_id>: [block ids]} }

# 2. Feed delta_block_ids VERBATIM into a group run; only those blocks translate
curl -s -X POST $BASE/group-runs \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"document_id": "<master>", "template_id": "end_to_end",
       "target_languages": "all", "block_ids": { "<doc_id>": ["<block id>", "…"] }}'

Ana belge üzerinde GET /documents/{id}/content?format=strings isteği yapıldığında, tüm dillerin çevirilerini birim kimliğine göre anahtarlanmış halde içeren tek bir .tstrings.json dosyası döner: Tek bir çağrıyla sonuçlar deponuza işlenmeye veya derleme sürecinize dahil edilmeye hazır hale gelir. İş hattınız bunun yerine belirli bir iletim formatı gerektiriyorsa, aynı uç nokta dile özel çıktılar da (markdown, html, csv, xliff, tmx) sunar; tam tabloyu Transept'i API ile Otomatikleştirin sayfasında bulabilirsiniz.

CSV, PO veya XLIFF formatında gelen kataloglarda, orijinal dosya dışa aktarımı bunun yerine kendi dosyanızın hücrelerini ve girdilerini doldurur (yüklediğiniz dosyanın baytı baytına aynısıdır, sadece çeviriler eklenmiştir); böylece dosya, geldiği sisteme doğrudan geri yüklenebilir.

curl -s "$BASE/documents/<master>/content?format=strings" \
  -H "Authorization: Bearer $KEY"
# → one .tstrings.json with every language keyed by unit id