Lokalizace přes API: řetězce, e-maily a dokumenty v uceleném procesu

Vše, co lze dělat v editoru, zvládne i skript: import, překlad do různých jazyků s využitím vašich glosářů a překladové paměti, korekturu i export. Tato příručka vás provede cestou od získání klíče až k přeloženému výstupu a následně vysvětlí každou část procesu. Interaktivní dokumentace a OpenAPI JSON představují kompletní technickou specifikaci; transept.ai/developers je pak jednostránková verze tohoto průvodce. Před prvním voláním ještě drobná poznámka k názvosloví: v uživatelském rozhraní jsou účtovací jednotkou slova, ale pole v odpovědích API si zachovávají historické označení credits (estimatedCredits, spendable). Jde o stejnou hodnotu.

Získání klíče

V aplikaci přejděte do Nastavení → Vývojář a zkopírujte si tajný klíč. V požadavcích jej pak uvádějte v hlavičce Authorization: Bearer tsk_live_… – vždy pouze v hlavičce, nikdy v URL.

Klíče mají definovaný rozsah oprávnění: buď plný přístup, nebo práva pro čtení a zápis v jednotlivých oblastech (dokumenty, běhy, glosáře, stylistické příručky, překladové paměti, webhooky a projekty). Volání mimo tento rozsah vrátí chybu 403 s upřesněním, co konkrétně chybí. Klíčem nelze vygenerovat jiný klíč; správa klíčů probíhá výhradně v aplikaci.

Celý proces v pěti voláních

Ověřte, že klíč funguje, vytvořte dokument, zjistěte cenu běhu, spusťte jej a načtěte výsledek.

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"

Tři návyky do začátku: nejprve si vyžádejte odhad (je zdarma; získáte rozmezí od minimální po maximální cenu, přičemž ta maximální se po dokončení srovná se skutečnou útratou), **posílejte ****Idempotency-Key** u POST požadavků vytvářejících úlohy (opakovaný pokus pak vrátí původní výsledek, místo aby se vám částka naúčtovala dvakrát) a zaregistrujte si webhook (POST /webhooks {url, events: ["group_run.completed"]}) namísto dotazování (polling). Doručování zpráv je podepsáno metodou HMAC, probíhá s opakovanými pokusy a k dispozici je i protokol doručování.

Tři podoby vstupu

Souvislý text a e-maily

POST /documents s content_type: "html" zachovává formátování, odkazy i zástupné symboly šablon i během překladu; format=html pak vrátí přeložený e-mail v původní podobě. Požadavek můžete i úplně přeskočit: stačí nastavit spouštěč workflow na „tělo požadavku je obsah“ a nasměrovat své ESP, Zapier/n8n nebo CI na URL spouštěče:

# 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.'

Spouštěč určuje, zda každé doručení vytvoří nový dokument, nebo aktualizuje jeden konkrétní (při aktualizaci se obsah znovu zarovná, aby se překládaly pouze změněné bloky). Opakovaná doručení se po dobu 24 hodin deduplikují podle external_id nebo hashe obsahu. Viz spouštěče webhooků.

Soubory

POST /documents/upload (multipart) se souborem a parametry source_language, target_language, volitelnými target_languages[] a project_id. U DOCX je zajištěn kompletní cyklus: export vloží překlady zpět do původního souboru, takže styl i rozvržení zůstanou zachovány. Soubory CSV, PO a XLIFF se importují jako jednotky s klíči a exportují se zpět ve svém formátu. Podrobnosti o formátech a mapování sloupců: soubory s řetězci.

Katalogy řetězců

Každý řetězec je jednotka se stálým id, polem source a volitelnými parametry context, max_length a placeholders:

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}

Kontext se k modelu dostává jako vodítko pro překlad, max_length se vynucuje metodou zkrácení a opakovaného pokusu, zástupné symboly jsou chráněny a tvary množného čísla se rozšiřují podle pravidel daného jazyka. Překlady, které už soubor obsahuje, se zdarma naimportují jako aktivní a naplní překladovou paměť. Pokud chybí cílové jazyky, volání selže s chybou no_target_languages, aby se neimportoval dokument, který by se neměl do čeho přeložit. Celý proces popisuje návod Lokalizace katalogu řetězců přes API.

Jedna e-mailová šablona, tři jazyky

Konkrétní příklad s e-mailem. Značky Liquid zůstávají během překladu nedotčeny:

# 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 | … }} se před předáním modelu zamaskuje a následně se v nezměněné podobě vrátí zpět. Jedinou výjimkou je náhradní hodnota friend – jde o text určený pro čtenáře, takže se PŘEKLÁDÁ, zatímco okolní značka nikoliv. Spusťte skupinu běhů podle rychlého průvodce a poté si načtěte jednotlivé jazyky zpět:

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

Bezobslužná varianta: spouštěč webhooku s payloadem si šablonu převezme přímo z ESP, workflow se spustí hned po doručení a webhook group_run.completed vrátí přeložené HTML zpět. Specifika konkrétních platforem (tagy Braze, podmínky Mailchimpu): e-mailové šablony ESP a průvodce lokalizací e-mailů.

Glosáře, stylistické příručky a překladová paměť

Vytvořte glosář a rovnou do něj v rámci stejného volání přidejte termíny:

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}]}'

Rozšiřte stávající glosář (seznam glosářů dostupných pro váš klíč získáte pomocí GET /glossaries):

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"}
      ]}'

Nebo je vygenerujte z dokumentu, kterému důvěřujete: pomocí POST /glossaries/{id}/auto-build a POST /styleguides/generate, přičemž obě mají bezplatné dvojče …/estimate. Obě jsou zpoplatněny podle počtu slov a obě vyžadují při volání přes API auto_apply: true; v headless režimu neprobíhá kontrola, takže se výsledek po dokončení rovnou uloží. Stav zjišťujte přes GET /generation-jobs/{id}. Alternativou s kontrolou v aplikaci je vytvoření z dokumentu. Stačí je připojit jednou a bez dalších nákladů se pak uplatní při každém dalším spuštění, ať už přes API, MCP, nebo v editoru:

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>"]}'

Stylistické příručky se připojují pomocí ID aktivní verze (získáte z GET /styleguides/{id}); zasláním [] je odpojíte. Obě akce lze provést i při vytváření dokumentu přes POST /documents. V uživatelském rozhraní: glosáře, stylistické příručky. Překladovou paměť není třeba připojovat: každý dokončený překlad se automaticky indexuje a znovu využívá. Můžete v ní vyhledávat (POST /translation-memory/query, zdarma), naplnit ji ze souborů TMX/XLIFF (POST /translation-memory/import, zdarma) nebo ji celou exportovat (GET /translation-memory/export-tmx). Viz překladová paměť a import stávajících překladů.

Týmy

Týmový klíč čerpá prostředky z týmového fondu a dědí týmové projekty, glosáře, stylistické příručky a překladovou paměť. Dokumenty v rámci týmu vytvoříte předáním project_id týmového projektu (seznam získáte přes GET /projects; týmové projekty obsahují parametr team_id). Vše ostatní funguje stejně jako u osobního účtu. Týmy a projekty se nastavují v aplikaci: projekty, týmy a pozvánky.

Běhy a kontrolní body

POST /runs zpracovává jednu jazykovou verzi, zatímco POST /group-runs pokryje všechny cílové jazyky a podle potřeby vytvoří ty chybějící. Obě metody nabízejí bezplatný odhad, přijímají Idempotency-Key a lze je zrušit. Krok workflow nastavený na čekání na kontrolu běh pozastaví: GET /runs/{id} pak vrací gate_pending: true se souhrnem zjištění. Pro lidi je tu panel kontroly a asistovaná kontrola; pro skripty pak:

# 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"

Kontrolní bod nikdy nepokračuje sám od sebe: schválení musí někdo nebo něco vyvolat, ať už je to váš skript, asistent přes MCP nebo člověk v aplikaci. Neexistuje žádný příznak, který by kontrolní body schválil už při spuštění běhu. Pokud se proces nemá nikde zastavovat, použijte workflow bez kroku kontroly.

Výstupní formáty

GET /documents/{id}/content?format=<f> pro ID jazykové verze:

Parametr format=strings u hlavního dokumentu vrátí všechny jazyky v rámci jednoho volání, připravené ke commitu.

Aktualizace pouze změn

U katalogů řetězců znovu odešlete celý aktuální soubor; o výpočet rozdílů se postará server:

# 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 @-

U nezměněných řetězců zůstávají zachovány překlady i stav revize; oprava jednoho řetězce stojí jeden řetězec. (Pokud při reimportu předáte parametr run: {template_id}, odešlou se změny ke zpracování v rámci stejného volání.) Jde o API variantu funkce Spouštět pouze u změn. U dokumentů s plynulým textem, u nichž došlo ke změně zdroje, endpoint POST /documents/{id}/resync-source znovu zarovná bloky: nezměněným blokům zůstanou překlady, změněné se označí jako neaktuální a spuštění omezené na změny pak zpracuje pouze je. Resynchronizace znovu parsuje uložený zdrojový soubor, proto zdroje upravujte přes import, nikoli přímými úpravami jednotlivých bloků.

AI asistenti (MCP)

Stejný cyklus jako u nástrojů pro agenty na adrese https://app.transept.ai/api/public/v1/mcp: me_get → document_create → group_run_estimate / group_run_start → group_run_get → document_content_get. Připojení probíhá přes OAuth (souhlas udělíte v prohlížeči, žádné vkládání klíče; pro headless režim funguje Bearer token). Nástroje respektují udělená oprávnění a u všeho, co spotřebovává slova, nejprve obdržíte odhad; asistent musí akci výslovně potvrdit. Nastavení pro jednotlivé klienty: Připojte svého AI asistenta.

Časté dotazy

Stojí odhady, reimporty nebo naimportované překlady nějaká slova?

Ne. Odhady jsou zdarma a bez vedlejších účinků. Bezplatný je i reimport katalogu (rozdíly se počítají na straně serveru) a překlady, které už vaše soubory obsahují, se naimportují jako hotová práce bez jakýchkoli nákladů. Slova čerpáte pouze tehdy, když pro vás Transept skutečně něco překládá. Odhady založené na horní hranici se po dokončení upraví podle skutečné spotřeby a nevyužitá rezerva se uvolní.

Může automatizace obejít mé schvalovací kroky?

Ne. Krok workflow nastavený na čekání na revizi běh pozastaví, dokud nedojde ke schválení: buď vaším skriptem volajícím endpoint pro schválení, nebo člověkem v aplikaci. Pokud má pipeline běžet plně automaticky od začátku do konce, nakonfigurujte workflow bez schvalovacího kroku. Neexistuje žádný parametr, který by umožnil obejít kontrolní bod, který jste do procesu sami vložili.

Je API dostupné i v bezplatném tarifu?

Ano. API klíče jsou k dispozici ve všech tarifech včetně verze Free; přístup k nim není nijak dodatečně omezen. Jediným limitem je váš zůstatek slov, úplně stejně jako v editoru. Měsíční příděl slov v bezplatném tarifu funguje přes API stejně jako kdekoli jinde.

Jak lokalizovat e-mailové šablony bez ručního exportu?

Nasměrujte svou e-mailovou platformu na webhookový trigger: tělo šablony odeslané v požadavku POST se stane dokumentem, workflow jej přeloží a export vrátí původní HTML strukturu s vloženými překlady. Zástupné symboly i syntaxe šablon zůstávají během celého procesu zachovány. Postupy pro jednotlivé platformy najdete v příručce pro lokalizaci e-mailů.

Kde najdu kompletní referenci k endpointům?

Interaktivní reference Swagger, generovaná ze stejné specifikace OpenAPI, kterou lze importovat do n8n, Zapieru nebo generátoru kódu (surový JSON). Tato příručka slouží jako srozumitelný průvodce; samotná specifikace je pak závazným kontraktem.