API ile uçtan uca yerelleştirme: dizeler, e-postalar ve belgeler

Editörün yapabildiği her şeyi bir betik de yapabilir: içe aktarma, sözlüğünüz ve çeviri belleğinizle diller arası çeviri, gözden geçirme ve dışa aktarma. Bu rehber sizi bir API anahtarından alıp çevrilmiş çıktıya ulaştıracak, ardından döngünün her bir aşamasından geçirecektir. Etkileşimli referans ve OpenAPI JSON tüm teknik detayları içeren eksiksiz kaynaklardır; transept.ai/developers ise bu rehberin tek sayfalık sürümüdür. İlk çağrıdan önce isimlendirmeyle ilgili küçük bir not: Faturalandırma birimi, kullanıcıların gördüğü her yerde kel****ime olarak geçer; ancak API yanıt alanlarında credits (estimatedCredits, spendable) şeklindeki eski adlandırma korunur. Miktar aynıdır.

Anahtar edinme

Uygulamada Ayarlar → Geliştirici kısmından gizli anahtarı bir kez kopyalayın. İsteklerde bu anahtar Authorization: Bearer tsk_live_… şeklinde, sadece başlık (header) olarak gönderilir; asla URL içinde gönderilmez.

Anahtarlar kapsam bazlıdır: Tam erişim sağlanabileceği gibi her alan (belgeler, çalıştırmalar, sözlükler, stil kılavuzları, çeviri belleği, webhook'lar, projeler) için ayrı ayrı okuma/yazma yetkisi de tanımlanabilir. Anahtarın yetki alanı dışındaki bir çağrı yapıldığında, eksik olan izni bildiren bir 403 hatası alınır. Bir anahtar asla yeni bir anahtar oluşturamaz; anahtar yönetimi yalnızca uygulama üzerinden gerçekleştirilir.

Beş çağrıda döngü

Anahtarın çalıştığını doğrulayın, bir doküman oluşturun, çalıştırma maliyetini hesaplayın, işlemi başlatın ve sonucu geri okuyun.

export KEY="tsk_live_…"
BASE="https://app.transept.ai/api/public/v1"

# 1: who am I, what can this key do, what's the balance?
curl -s $BASE/me -H "Authorization: Bearer $KEY"

# 2: a document plus its target-language fan-out, in one call
curl -s -X POST $BASE/documents \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"title": "Welcome email", "content": "# Welcome\n\nStart your free trial.",
       "content_type": "markdown", "source_language": "en",
       "target_language": "de", "target_languages": ["fr", "uk"]}'
# → { document_id, language_group: [ {id, target_language}, … ] }

# 3: price it (free, no side effects), then run it across every language
curl -s $BASE/workflow-templates -H "Authorization: Bearer $KEY"   # discover ids

curl -s -X POST $BASE/group-runs/estimate \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"document_id": "<master>", "template_id": "end_to_end", "target_languages": "all"}'
# → { lanes: [ {language, estimatedCredits, minCredits} ], totals: {sufficient} }

curl -s -X POST $BASE/group-runs \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome-2026-08-05" \
  -d '{"document_id": "<master>", "template_id": "end_to_end", "target_languages": "all"}'
# → { id: <group_run_id>, runs: [ {job_id, language, block_count} ] }

# 4: wait by polling, or get pushed a signed event instead
curl -s $BASE/group-runs/<group_run_id> -H "Authorization: Bearer $KEY"
# → { status, runs: [ {language, status, progress, gate} ] }

# 5: read the results in the format your pipeline wants
curl -s "$BASE/documents/<version-id>/content?format=markdown" \
  -H "Authorization: Bearer $KEY"

İlk günden itibaren şu üç alışkanlığı edinin: önce maliyet tahmini alın (ücretsizdir; sunulan aralık taban ve tavan fiyatları belirtir, tavan fiyat ise işlem sonunda gerçek harcama tutarına çekilir), iş oluşturan POST isteklerinde bir **Idempotency-Key** gönderin (böylece yeniden denemeler, mükerrer faturalandırma yerine ilk sonucu döndürür) ve sürekli sorgu yapmak (polling) yerine bir webhook kaydedin (POST /webhooks {url, events: ["group_run.completed"]}). Gönderimler HMAC imzalıdır; yeniden deneme desteği ve gönderim günlüğü mevcuttur.

Üç farklı girdi biçimi

Düz metin ve e-posta

content_type: "html" parametresiyle kullanılan POST /documents uç noktası, biçimlendirmeyi, bağlantıları ve şablon yer tutucularını çeviri süreci boyunca korur; format=html ise çevrilen e-postayı aynı yapıda geri döndürür. Dilerseniz bu isteği tamamen atlayabilirsiniz: Bir iş akışı tetikleyicisini "istek gövdesi içeriktir" olarak ayarlayın ve ESP, Zapier/n8n veya CI sisteminizi tetikleyici URL'sine yönlendirin:

# the trigger URL (with its secret) comes from the workflow's trigger card;
# the secret IS the auth, so no Authorization header
curl -s -X POST $BASE/hooks/<trigger-secret> \
  -H "Content-Type: application/json" \
  -d '{"content": "<h1>Welcome!</h1><p>Your trial starts today.</p>",
       "content_type": "html",
       "title": "Trial welcome",
       "external_id": "welcome-v4"}'
# → 202 { run id, document_id, created }

# raw bodies work too: POST the markdown/HTML itself with its Content-Type
curl -s -X POST $BASE/hooks/<trigger-secret> \
  -H "Content-Type: text/markdown" \
  --data-binary $'# Welcome\n\nStart your free trial.'

Tetikleyici, her gönderimin yeni bir doküman mı oluşturacağını yoksa sabit bir dokümanı mı güncelleyeceğini belirler (güncelleme işlemi içeriği yeniden hizalar, böylece sadece değişen bloklar tekrar çevrilir). Tekrarlanan gönderimler, 24 saat boyunca external_id veya içerik karması (hash) üzerinden tekilleştirilir. Bkz. webhook tetikleyicileri.

Dosyalar

POST /documents/upload (multipart) ile dosyayı; source_language, target_language, isteğe bağlı target_languages[] ve project_id parametreleriyle birlikte iletin. DOCX dosyalarında süreç çift yönlüdür: Dışa aktarma işlemi çevirileri orijinal dosyanıza geri işler, böylece stil ve düzen bozulmadan korunur. CSV, PO ve XLIFF dosyaları anahtarlı birimler olarak içe aktarılır ve tekrar kendi formatlarında dışa aktarılır. Format detayları ve sütun eşleme: dize dosyaları.

Dize katalogları

Her dize; sabit bir id, bir source ve isteğe bağlı context, max_length ve placeholders alanlarından oluşan bir birimdir:

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}

Bağlam, modele çeviri yönergesi olarak iletilir; max_length sınırı "kısalt ve tekrar dene" yöntemiyle uygulanır, yer tutucular korunur ve çoğul yapılar her dile göre genişletilir. Dosyada halihazırda bulunan çeviriler, sisteme ücretsiz olarak aktif çeviri şeklinde aktarılır ve çeviri belleğini besler. Hedef dillerin eksik olması durumunda, hiçbir sonuç üretmeyecek bir dokümanı içe aktarmak yerine çağrı no_target_languages hatasıyla sonlandırılır. Sürecin tamamı için: API üzerinden dize kataloğu yerelleştirme.

Tek e-posta şablonu, üç dil

E-posta örneğini somutlaştıralım. Liquid etiketleri çeviri sürecinde yapısını aynen korur:

# the template body goes in as HTML; three target languages fan out
curl -s -X POST $BASE/documents \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"title": "Trial welcome", "content_type": "html", "source_language": "en",
       "target_languages": ["de", "fr", "uk"],
       "content": "<h1>Welcome, {{ first_name | default:\"friend\" }}!</h1><p>Your trial starts today.</p>"}'

{{ first_name | … }} yapısı, model metni görmeden önce maskelenir ve ardından aynen geri yüklenir. Tek bir istisna vardır: Yedek metin olan friend doğrudan okuyucuya yönelik olduğu için çevrilir, ancak onu sarmalayan etiket olduğu gibi bırakılır. Grubu hızlı başlangıç kılavuzundaki gibi çalıştırın ve ardından her dildeki sonucu geri okuyun:

curl -s "$BASE/documents/<de-version-id>/content?format=html" \
  -H "Authorization: Bearer $KEY"
# → the same HTML with German copy, Liquid intact; paste it into the ESP's de variant

Sıfır temaslı seçenek: Bir veri yükü webhook tetikleyicisi şablonu doğrudan ESP'den alır, iş akışı veri ulaştığı anda çalışır ve group_run.completed webhook'u çevrilmiş HTML'i geri iletir. Platforma özgü detaylar (Braze etiketleri, Mailchimp koşullu ifadeleri): ESP e-posta şablonları ve e-posta yerelleştirme kılavuzu.

Sözlükler, stil kılavuzları ve çeviri belleği

Aynı çağrıda terimleri de ekleyerek bir sözlük oluşturun:

curl -s -X POST $BASE/glossaries \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"name": "Product terms", "source_language": "en",
       "terms": [{"source_term": "Transept", "target_term": "Transept",
                  "do_not_translate": true}]}'

Mevcut bir sözlüğü genişletin (GET /glossaries anahtarınızın görebildiği sözlükleri listeler):

curl -s -X POST $BASE/glossaries/<id>/terms/bulk \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"terms": [
        {"source_term": "workspace", "target_term": "Arbeitsbereich"},
        {"source_term": "run", "target_term": "Lauf", "notes": "the noun: a workflow execution"}
      ]}'

Veya güvendiğiniz bir dokümandan oluşturun: Her birinin ücretsiz bir …/estimate eşi bulunan POST /glossaries/{id}/auto-build ve POST /styleguides/generate uç noktalarını kullanın. Her iki işlem de kelime üzerinden ücretlendirilir ve API kullanımında auto_apply: true parametresini gerektirir; arayüzsüz (headless) kullanımda inceleme adımı yoktur, bu nedenle sonuçlar tamamlandığında doğrudan kaydedilir. GET /generation-jobs/{id} üzerinden durumu sorgulayın. Uygulama içinden inceleme yapabileceğiniz alternatif: dokümandan oluşturun. Bir kez bağladığınızda; API, MCP veya editör fark etmeksizin sonraki tüm çalıştırmalar bunları ek ücret ödemeden kullanır:

curl -s -X PATCH $BASE/documents/<id>/translation-settings \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"glossary_ids": ["<glossary_id>"], "styleguide_version_ids": ["<active_version_id>"]}'

Stil kılavuzları aktif versiyon kimliği (GET /styleguides/{id} üzerinden) ile bağlanır; [] bağlantıyı keser; her iki yöntem de oluşturma aşamasında POST /documents üzerinde çalışır. Kullanıcı arayüzü tarafı: sözlükler, stil kılavuzları. Çeviri belleğinin bağlanmasına gerek yoktur: Tamamlanan her çeviri otomatik olarak dizine eklenir ve tekrar kullanılır. Belleği sorgulayabilir (POST /translation-memory/que``ry, ücretsiz), bir TMX/XLIFF dosyasından veri yükleyebilir (POST /translation-memory/import, ücretsiz) veya tümünü dışa aktarabilirsiniz (GET /translation-memory/export-tmx). Bkz. çeviri belleği ve mevcut çevirileri getirme.

Ekipler

Bir ekip anahtarı, ekip havuzu üzerinden ücretlendirilir ve ekibin projelerini, sözlüklerini, stil kılavuzlarını ve çeviri belleğini devralır. Ekip bünyesinde doküman oluşturmak için bir ekip projesine ait project_id bilgisini (GET /projects; ekip projeleri bir team_id taşır) iletmeniz yeterlidir. Bunun dışındaki her şey bireysel kullanımla aynıdır. Ekipler ve projeler uygulama içinden yapılandırılır: projeler, ekipler ve davetler.

Çalıştırmalar ve inceleme onay noktaları

POST /runs tek bir dil versiyonu üzerinde çalışır; POST /group-runs ise gerektiğinde eksik versiyonları da oluşturarak tüm hedef dillere yayılır. Her iki işlem için de ücretsiz tahmin alınabilir, Idempotency-Key kullanılabilir ve işlemler iptal edilebilir. İnce****leme bekle (wait for review) olarak ayarlanan bir iş akışı adımı, çalıştırmayı askıya alır: GET /runs/{id} çağrısı, inceleme bulgularının bir özetiyle birlikte gate_pending: true bilgisini döndürür. Bu duraklamanın kullanıcı tarafındaki karşılığı inceleme paneli ve rehberli inceleme iken, kod tarafındaki işleyiş şöyledir:

# continue downstream steps (all blocks, or a reviewed subset):
curl -s -X POST $BASE/runs/<id>/gate/approve \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"approved_block_ids": ["…"]}'    # omit the field to approve all

# a gate with nothing downstream is dismissed instead:
curl -s -X POST $BASE/runs/<id>/gate/acknowledge -H "Authorization: Bearer $KEY"

Bir onay noktası asla kendiliğinden devam etmez: İster kodunuz, ister MCP üzerinden bir asistan, ister uygulamadaki bir kişi olsun, birinin onay (approve) vermesi gerekir. Onay noktalarını önceden onaylayan bir çalıştırma başlatma bayrağı yoktur; sürecin hiçbir noktada duraklamasını istemiyorsanız inceleme adımı içermeyen bir iş akışı kullanın.

Çıktı formatları

Bir dil versiyonu kimliği (id) üzerinde GET /documents/{id}/content?format=<f>:

**master** doküman üzerinde format=strings kullanımı, tüm dilleri tek bir çağrıda ve kaydedilmeye hazır şekilde döndürür.

Sadece değişen kısımları güncelleyin

Dize katalogları için mevcut dosyanın tamamını tekrar gönderin; farkı sunucu hesaplar:

# 1: re-import the complete current corpus; Transept 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 > delta.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
jq -n --slurpfile d delta.json \
  '{document_id: $d[0].master_document_id, template_id: "end_to_end",
    target_languages: "all", block_ids: $d[0].delta_block_ids}' \
| curl -s -X POST $BASE/group-runs \
    -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" --data-binary @-

Değişmeyen dizeler hem çevirilerini hem de inceleme durumunu korur; bir dizeyi düzeltmenin maliyeti yalnızca bir dizedir. (Farkı aynı çağrıyla iletmek için yeniden içe aktarma sırasında run: {template_id} parametresini satır içi olarak gönderin.) Bu işlem, Sadece değişenleri çalıştır özelliğinin API tarafındaki karşılığıdır. Kaynak metni değişen düzyazı dokümanları için POST /documents/{id}/resync-source uç noktası blokları yeniden hizalar: Değişmeyen bloklar çevirilerini korur, değişenler "eskimiş" olarak işaretlenir ve sadece güncellenenleri hedefleyen bir çalıştırma yalnızca bu bloklara dokunur. Yeniden senkronizasyon işlemi kayıtlı kaynak dosyayı tekrar ayrıştırdığı için kaynak metinlerini bloklar üzerinde yama yaparak değil, içe aktarma yoluyla düzenleyin.

Yapay zeka asistanları (MCP)

https://app.transept.ai/api/public/v1/mcp adresindeki işleyiş, agent araçlarıyla aynı döngüyü takip eder: me_get → document_create → group_run_estimate / group_run_start → group_run_get → document_content_get. Bağlantı OAuth ile sağlanır (tarayıcı üzerinden onay verilir, anahtar yapıştırmanıza gerek yoktur; headless sistemler için Bearer anahtarı kullanılabilir). Araçlar tanımlanan izinlere uygun hareket eder ve kelime harcayan her işlem önce bir maliyet tahmini sunar; asistanın bu işlemi açıkça onaylaması şarttır. İstemci bazlı kurulum: Yapay zeka asistanınızı bağlayın.

SSS

Tahminler, yeniden içe aktarmalar veya sisteme işlenen çeviriler kelime harcar mı?

Hayır. Tahminler ücretsizdir ve herhangi bir yan etki yaratmaz. Bir kataloğu yeniden içe aktarmak ücretsizdir (fark sunucu tarafında hesaplanır); dosyalarınızda halihazırda bulunan çeviriler ise tamamlanmış iş olarak sisteme ücretsiz bir şekilde aktarılır. Kelime bakiyesi yalnızca Transept sizin için bir çeviri yaptığında harcanır. Üst sınır tahminleri, işlem sonunda gerçek harcama tutarına göre kesinleşir ve kullanılmayan rezervler serbest bırakılır.

Otomasyon inceleme aşamalarımı atlayabilir mi?

Hayır. İnceleme bekleyecek şekilde ayarlanan bir iş akışı adımı, bir onay gelene kadar işlemi askıya alır: Bu onay, ya gate-approve uç noktasını çağıran bir betik ya da uygulama içindeki bir kişi tarafından sağlanır. Eğer bir iş hattının uçtan uca müdahale gerektirmeden çalışması gerekiyorsa, iş akışını inceleme adımı olmayacak şekilde yapılandırın; sisteme eklediğiniz bir onay aşamasını atlamanızı sağlayacak bir parametre yoktur.

API, Ücretsiz planda kullanılabilir mi?

Evet. API anahtarları, Ücretsiz plan dahil tüm paketlerde sunulmaktadır; bu konuda ayrı bir kısıtlama bulunmaz. Tıpkı editörde olduğu gibi kullanımı belirleyen tek sınır kelime bakiyenizdir. Ücretsiz planın aylık kelime hakkı, API kullanımında da diğer her yerde olduğu gibi geçerlidir.

E-posta şablonlarını manuel olarak dışa aktarmadan nasıl yerelleştirebilirim?

E-posta platformunuzu bir veri yükü (payload) webhook tetikleyicisine yönlendirin: POST edilen şablon gövdesi dokümana dönüştürülür, iş akışı tarafından çevrilir ve dışa aktarma işlemi, çevirilerin yerleştirildiği orijinal HTML yapısını döndürür. Yer tutucular ve şablon sözdizimi bu döngü boyunca korunur. Platform bazlı işleyiş ayrıntılarını e-posta yerelleştirme kılavuzunda bulabilirsiniz.

Kapsamlı uç nokta referansına nereden ulaşabilirim?

Etkileşimli Swagger referansı, n8n, Zapier veya bir kod oluşturucuya aktarabileceğiniz OpenAPI spesifikasyonunun (ham JSON) aynısından üretilmiştir. Bu kılavuz konuya anlatısal bir giriş sunar; spesifikasyon ise işin asıl teknik sözleşmesidir.