Localizzare un catalogo di stringhe tramite API

Il formato indicizzato di Transept è .tstrings.json: un elenco di unità, ciascuna con un id stabile, una source e, opzionalmente, un context (cos'è la stringa e dove compare), una max_length e dei placeholders. L'id è il contratto: è il modo in cui le traduzioni mantengono la propria identità tra una re-importazione e l'altra, come lo stato della revisione viene preservato e come l'esportazione indicizza ogni lingua. Entrambi i parametri extra svolgono un lavoro concreto: il contesto arriva al modello come guida per la traduzione, mentre il limite di caratteri viene applicato tramite un sistema automatico di accorciamento e nuovo tentativo.

I file CSV, gettext PO e XLIFF vengono importati come le stesse unità indicizzate tramite l'app o l'endpoint di caricamento; consulta file di stringhe per i dettagli sulla mappatura di ogni formato. Questo articolo spiega come gestire il ciclo tramite codice, dove il formato nativo è .tstrings.json.

POST /documents/import-strings con il catalogo in formato JSON. La risoluzione delle lingue di destinazione segue un ordine fisso: i parametri espliciti target_language / target_languages nella richiesta hanno la precedenza; in caso contrario, vengono usati i target_locales nell'intestazione del catalogo. Se non viene specificata alcuna lingua, la chiamata fallisce immediatamente con no_target_languages invece di importare un documento senza destinazioni. La chiamata restituisce un processing_job_id; interroga (poll) GET /document-jobs/{id} finché l'importazione non termina e non avrai ottenuto gli ID del documento.

Le traduzioni già presenti nel file (targets: {de: "…"}) vengono caricate come traduzione attiva di ogni stringa, gratuitamente e senza bisogno di avviare un'elaborazione, alimentando immediatamente la tua memoria di traduzione. Il comportamento è identico a quello dell'importazione di traduzioni esistenti tramite l'app.

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

Invia nuovamente l'intero catalogo aggiornato all'endpoint POST /documents/{id}/import-strings, senza rimuovere alcuna parte. Il server esegue un confronto (diff) in base all'ID dell'unità e restituisce i risultati rilevati (added, changed, unchanged, removed) insieme ai delta_block_ids: i blocchi esatti che necessitano di traduzione per ogni lingua. Passando questo oggetto così com'è nel parametro block_ids di un group run, verranno tradotti solo quei blocchi; puoi anche includere il parametro run direttamente nella richiesta di re-importazione per elaborare le differenze con la stessa chiamata.

Le unità invariate conservano le proprie traduzioni e l'eventuale revisione già effettuata; questa è la controparte API della funzione Traduci solo i contenuti aggiornati. Correggere una sola stringa in un catalogo di centinaia avrà il costo di una singola stringa.

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

GET /documents/{id}/content?format=strings sul documento principale restituisce un unico file .tstrings.json con le traduzioni di tutte le lingue mappate per ID unità: una sola chiamata, e il file è pronto per il commit o per essere integrato nella tua build. Lo stesso endpoint fornisce versioni per singola lingua (markdown, html, csv, xliff, tmx) se la pipeline necessita di un formato di scambio specifico; la tabella completa è disponibile in Automatizzare Transept tramite API.

Per i cataloghi importati come CSV, PO o XLIFF, l'esportazione del file originale compila le celle e le voci del tuo file (mantenendolo identico all'originale, con l'aggiunta delle traduzioni), permettendoti di ricaricarlo direttamente nel sistema da cui proviene.

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