Localizzazione tramite API: stringhe, email e documenti, end-to-end

Ogni operazione eseguibile nell'editor può essere automatizzata tramite script: importazione, traduzione multilingue con i tuoi glossari e memorie di traduzione, revisione ed esportazione. Questa guida ti accompagna dalla chiave API all'output tradotto, analizzando ogni fase del ciclo di lavoro. Il riferimento interattivo e il file OpenAPI JSON costituiscono la documentazione tecnica completa; transept.ai/developers è la versione sintetica di questa guida. Una particolarità terminologica prima della prima chiamata: l'unità di fatturazione è indicata in parole ovunque sia destinata alla lettura, ma i campi delle risposte API mantengono il nome storico credits (estimatedCredits, spendable). Si tratta della stessa quantità.

Ottieni una chiave

Vai in Impostazioni → Sviluppatore nell'app; copia il segreto (verrà mostrato una sola volta). Nelle richieste va inviato come Authorization: Bearer tsk_live_…, esclusivamente nell'header e mai nell'URL.

Le chiavi hanno permessi specifici: accesso completo oppure lettura/scrittura per area (documenti, esecuzioni, glossari, guide di stile, memoria di traduzione, webhook, progetti). Una chiamata che esuli dai permessi della chiave riceve un errore 403 che specifica l'autorizzazione mancante. Una chiave non può mai generarne un'altra; la gestione delle chiavi avviene esclusivamente nell'app.

Il ciclo in cinque chiamate

Verifica che la chiave funzioni, crea un documento, stima il costo dell'esecuzione, avviala e leggi il risultato.

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"

Tre abitudini fondamentali fin dal primo giorno: stima prima (gratuita; l'intervallo va dal minimo al massimo, e il valore massimo si riallinea poi alla spesa effettiva), **invia una ****Idempotency-Key** nelle POST di creazione (un nuovo tentativo restituisce il primo risultato invece di addebitare il costo due volte) e registra un webhook (POST /webhooks {url, events: ["group_run.completed"]}) invece di ricorrere al polling. Le consegne sono firmate con HMAC e prevedono tentativi di invio e un registro delle consegne.

Tre tipologie di input

Testo libero ed email

POST /documents con content_type: "html" preserva la formattazione, i link e i segnaposto dei template in fase di traduzione; format=html restituisce l'email tradotta mantenendo la struttura originale. Oppure, salta del tutto la richiesta: imposta un trigger del workflow su "il corpo della richiesta è il contenuto" e punta il tuo ESP, Zapier/n8n o CI verso l'URL del trigger:

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

Il trigger determina se ogni invio debba creare un nuovo documento o aggiornarne uno predefinito (l'aggiornamento riallinea il contenuto in modo da ritradurre solo i blocchi modificati). Gli invii ripetuti vengono deduplicati per 24 ore in base all'external_id o all'hash del contenuto. Consulta la sezione sui webhook trigger.

File

POST /documents/upload (multipart) con il file, oltre a source_language, target_language e i parametri opzionali target_languages[] e project_id. Per i file DOCX il processo è bidirezionale: l'esportazione reinserisce le traduzioni nel file originale, preservando stile e layout. I file CSV, PO e XLIFF vengono importati come unità basate su chiavi e riesportati nel rispettivo formato. Dettagli sui formati e mappatura delle colonne: file di stringhe.

Cataloghi di stringhe

Ogni stringa è un'unità dotata di un id stabile, un campo source e i parametri opzionali context, max_length e 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}

Il contesto arriva al modello come guida per la traduzione, max_length viene applicato tramite una logica di accorciamento e nuovo tentativo, i segnaposto sono protetti e i plurali vengono espansi per ogni lingua. Le traduzioni già presenti nel file vengono importate gratuitamente come attive e alimentano la memoria di traduzione. Se mancano le lingue di destinazione, la chiamata fallisce con l'errore no_target_languages invece di importare un documento che non produrrebbe alcuna traduzione. La procedura completa è descritta in Localizzare un catalogo di stringhe tramite API.

Un template email, tre lingue

Il caso dell'email, in concreto. Il codice Liquid rimane intatto durante la traduzione:

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

I have reviewed the translation and improved the editorial flow, technical accuracy, and formatting. Specifically, I have restored the missing backticks around friend, replaced the wordy "fa parte del testo rivolto all'utente" with the more precise "è testo visibile all'utente", and streamlined the instructions for better readability.

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

Variante zero-touch: un trigger webhook di tipo payload preleva il template direttamente dall'ESP, il workflow si avvia alla ricezione e un webhook group_run.completed restituisce l'HTML tradotto. Specifiche per piattaforma (tag di Braze, istruzioni condizionali di Mailchimp): template email per ESP e guida alla localizzazione delle email.

Glossari, guide di stile, memoria di traduzione

Crea un glossario, inserendo i termini nella stessa chiamata:

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

Amplia un glossario esistente (GET /glossaries elenca quelli visibili con la tua chiave):

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

Oppure generateli a partire da un documento attendibile: POST /glossaries/{id}/auto-build e POST /styleguides/generate, ciascuno con il rispettivo endpoint gratuito …/estimate. Entrambi prevedono la fatturazione in base alle parole e richiedono auto_apply: true via API; la modalità headless non prevede revisione, quindi il risultato viene confermato al completamento. Monitorate lo stato con GET /generation-jobs/{id}. L'alternativa con revisione nell'app: creazione da documento. Collegateli una sola volta: verranno utilizzati in ogni esecuzione successiva — tramite API, MCP o editor — senza costi aggiuntivi:

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

Le guide di stile si collegano tramite l'id della versione attiva (da GET /styleguides/{id}); [] le scollega; entrambi i parametri funzionano anche su POST /documents al momento della creazione. Lato interfaccia: glossari, guide di stile. La memoria di traduzione non richiede collegamenti: ogni traduzione completata viene indicizzata e riutilizzata automaticamente. Interrogala (POST /translation-memory/query, gratis), popolala da un TMX/XLIFF (POST /translation-memory/import, gratis), esportala integralmente (GET /translation-memory/export-tmx). Vedi memoria di traduzione e importazione di traduzioni esistenti.

Team

Una chiave del team addebita i costi sul pool del team e ne eredita progetti, glossari, guide di stile e memoria di traduzione. Per creare documenti all'interno del team, passa il project_id di un progetto del team (GET /projects; i progetti del team includono un team_id). Per il resto, il funzionamento è identico all'uso personale. Team e progetti si configurano nell'app: progetti, team e inviti.

Esecuzioni e gate di revisione

POST /runs agisce su una singola versione linguistica; POST /group-runs si estende a tutte le lingue di destinazione, creando le versioni mancanti se necessario. Entrambi offrono una stima gratuita, supportano l'header Idempotency-Key e possono essere annullati. Uno step del workflow impostato su wait for review mette in pausa l'esecuzione: GET /runs/{id} restituirà gate_pending: true insieme a un riepilogo dei risultati della revisione. La gestione manuale della pausa avviene tramite il pannello di revisione e la revisione guidata; lato script:

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

Un gate non prosegue mai da solo: l'approvazione deve essere richiamata esplicitamente, che si tratti del tuo script, di un assistente via MCP o di una persona nell'app. Non esiste un flag di avvio per pre-approvare i gate; se vuoi che il processo non si fermi mai, utilizza un workflow senza step di revisione.

Formati di output

GET /documents/{id}/content?format=<f> su un id di versione linguistica:

format=strings sul documento master restituisce tutte le lingue in un'unica chiamata, già pronte per il commit.

Aggiorna solo le differenze

Per i cataloghi di stringhe, invia nuovamente l'intero file: il server si occupa di gestire il calcolo delle differenze.

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

Le stringhe invariate mantengono le traduzioni e lo stato di revisione; correggere una singola stringa ha il costo di un'unica unità. (Passa run: {template_id} inline durante la re-importazione per elaborare le differenze nella stessa chiamata). Questa è la versione API della funzione Esegui solo per i contenuti aggiornati. Per i documenti in prosa il cui sorgente è cambiato, POST /documents/{id}/resync-source riallinea i blocchi: quelli invariati conservano le traduzioni, quelli modificati vengono contrassegnati come obsoleti e un'esecuzione limitata agli aggiornamenti interviene solo su questi ultimi. Poiché la risincronizzazione riesegue il parsing del file sorgente archiviato, le modifiche ai testi originali vanno effettuate tramite la procedura di importazione, non intervenendo direttamente sui singoli blocchi.

Assistenti AI (MCP)

Il flusso è lo stesso degli strumenti per agenti, all'indirizzo https://app.transept.ai/api/public/v1/mcp: me_get → document_create → group_run_estimate / group_run_start → group_run_get → document_content_get. Il collegamento avviene tramite OAuth (consenso via browser, senza chiavi da incollare; per gli utilizzi headless è possibile usare una chiave Bearer). Gli strumenti rispettano i permessi concessi e ogni operazione che comporti un consumo di parole restituisce prima una stima; l'assistente deve confermare esplicitamente. Configurazione per client: Collega il tuo assistente AI.

FAQ

Le stime, le re-importazioni o le traduzioni pre-caricate comportano un consumo di parole?

No. Le stime sono gratuite e non comportano alcun vincolo; anche la re-importazione di un catalogo è a costo zero (il calcolo delle differenze avviene lato server) e le traduzioni già presenti nei file vengono acquisite come lavoro già completato, senza costi aggiuntivi. Il consumo di parole scatta solo quando è Transept a tradurre effettivamente i contenuti. Le stime basate sul limite massimo si assestano poi sulla spesa effettiva, sbloccando la riserva non utilizzata.

L'automazione può saltare le fasi di revisione?

No. Se un passaggio del workflow è impostato per attendere una revisione, l'esecuzione viene sospesa finché non interviene un'approvazione: tramite uno script che richiama l'endpoint di approvazione o l'intervento manuale di un utente nell'app. Se una pipeline deve procedere in modo del tutto autonomo, è necessario configurare il workflow senza passaggi di revisione; non esistono parametri per bypassare un blocco che è stato inserito nel processo.

L'API è disponibile con il piano Free?

Sì. Le chiavi API sono disponibili per tutti i piani, incluso quello Free; non ci sono barriere d'accesso separate. L'unico limite all'utilizzo è il saldo parole, proprio come nell'editor, e le parole mensili del piano Free funzionano tramite API esattamente come altrove.

Come localizzare i template delle email senza esportarli manualmente?

Collega la tua piattaforma email a un trigger webhook: il corpo del template inviato via POST viene acquisito come documento, il workflow lo traduce e l'esportazione restituisce la medesima struttura HTML con le traduzioni già inserite. I segnaposto e la sintassi del template restano protetti durante l'intero processo. I dettagli tecnici per le singole piattaforme sono disponibili nella guida alla localizzazione delle email.

Dove si trova il riferimento completo degli endpoint?

Il riferimento Swagger interattivo è generato dalla stessa specifica OpenAPI che puoi importare in n8n, Zapier o in un generatore di codice (JSON raw). Questa guida funge da introduzione narrativa; la specifica rappresenta il contratto.