Localisez vos contenus via l'API : chaînes de caractères, e-mails et documents de bout en bout

Toutes les actions de l'éditeur sont accessibles par script : import, traduction multilingue avec vos glossaires et mémoires de traduction, révision et export. Ce guide vous accompagne de la configuration de votre clé jusqu'à l'obtention des résultats, avant de détailler chaque étape du processus. La référence interactive et le fichier JSON OpenAPI constituent la documentation technique complète ; la page transept.ai/developers en propose une version synthétique. Une précision terminologique avant votre premier appel : l'unité de facturation est le mot dans l'interface utilisateur, mais les champs de réponse de l'API conservent l'appellation historique credits (estimatedCredits, spendable). Il s'agit de la même valeur.

Obtenir une clé

Rendez-vous dans l'onglet Paramètres → Développeur de l'application et copiez le secret une seule fois. Les requêtes le transmettent via l'en-tête Authorization: Bearer tsk_live_… — uniquement dans l'en-tête, jamais dans l'URL.

Les clés disposent de portées : accès complet ou droits de lecture/écriture par domaine (documents, exécutions, glossaires, guides de style, mémoire de traduction, webhooks, projets). Tout appel sortant de ce périmètre renvoie une erreur 403 précisant les droits manquants. Une clé ne peut jamais en générer une autre ; la gestion des clés s'effectue exclusivement dans l'application.

Le cycle en cinq appels

Vérifiez le fonctionnement de votre clé, créez un document, estimez le coût de l'exécution, lancez-la, puis récupérez le résultat.

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"

Trois réflexes à adopter dès le premier jour : estimez d'abord le coût (c'est gratuit ; la fourchette va du minimum au maximum, et le plafond s'ajuste ensuite à la dépense réelle), **envoyez une ****Idempotency-Key** lors des requêtes POST de création de tâches (un nouvel essai renvoie le résultat initial au lieu de facturer deux fois) et enregistrez un webhook (POST /webhooks {url, events: ["group_run.completed"]}) plutôt que de recourir au polling. Les envois sont signés par HMAC et s'accompagnent d'un système de relances et d'un journal d'envoi.

Trois formats d'entrée

Texte suivi et e-mails

L'appel POST /documents avec content_type: "html" préserve la mise en forme, les liens et les balises de modèle lors de la traduction ; format=html renvoie l'e-mail traduit à l'identique. Ou passez-vous de l'appel manuel : configurez un déclencheur de workflow sur « le corps de la requête est le contenu » et faites pointer votre ESP, Zapier/n8n ou votre CI vers l'URL du déclencheur :

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

Le déclencheur détermine si chaque envoi génère un nouveau document ou met à jour un document fixe (une mise à jour réaligne le contenu pour ne traduire que les blocs modifiés). Les envois répétés sont dédoublonnés via l'identifiant external_id ou le hachage du contenu pendant 24 heures. Consultez la section sur les déclencheurs par webhook.

Fichiers

POST /documents/upload (multipart) avec le fichier, ainsi que source_language, target_language, target_languages[] (facultatif) et project_id. Le DOCX gère le cycle complet : l'exportation réinjecte les traductions dans votre fichier d'origine, préservant ainsi le style et la mise en page. Les fichiers CSV, PO et XLIFF sont importés sous forme d'unités avec clés et réexportés dans leur format initial. Détails des formats et mappage des colonnes : fichiers de chaînes.

Catalogues de chaînes

Chaque chaîne constitue une unité dotée d'un id stable, d'une source et, en option, de champs context, max_length et 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}

Le champ context sert de guide de traduction pour le modèle, la limite max_length est respectée grâce à un mécanisme de réduction et de nouvel essai, les variables sont protégées et les pluriels sont déclinés selon chaque langue. Les traductions déjà présentes dans le fichier sont importées gratuitement comme versions actives et alimentent la mémoire de traduction. Si aucune langue cible n'est définie, l'appel échoue avec l'erreur no_target_languages plutôt que d'importer un document qui ne mènerait à aucune traduction. Le cycle complet est décrit dans le guide Localiser un catalogue de chaînes via l'API.

Un modèle d'e-mail, trois langues

Voici un exemple concret pour les e-mails. Les balises Liquid sont préservées lors de la traduction :

# 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 | … }} est masqué avant d'être soumis au modèle, puis restauré à l'identique. Une seule exception : le texte de secours friend est destiné au lecteur ; il EST donc traduit, contrairement à la balise qui l'entoure. Lancez l'exécution groupée comme indiqué dans le guide de démarrage rapide, puis récupérez le contenu pour chaque langue :

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 « zéro intervention » : un déclencheur par webhook avec payload récupère le modèle directement depuis l'ESP, le workflow s'exécute dès réception et un webhook group_run.completed restitue le code HTML traduit. Spécificités par plateforme (balises Braze, conditions Mailchimp) : modèles d'e-mail ESP et le guide de localisation d'e-mails.

Glossaires, guides de style et mémoire de traduction

Créez un glossaire en y intégrant des termes dès le premier appel :

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

Enrichissez un glossaire existant (GET /glossaries liste ceux accessibles avec votre clé) :

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

Vous pouvez aussi les générer à partir d'un document fiable : POST /glossaries/{id}/auto-build et POST /styleguides/generate, chacun disposant d'un équivalent gratuit …/estimate. Ces deux méthodes sont facturées au mot et nécessitent toutes deux auto_apply: true via l'API ; le mode sans interface (headless) ne comportant pas d'étape de révision, le résultat est validé dès la fin du processus. Interrogez GET /generation-jobs/{id} pour suivre l'avancement. L'alternative avec révision intégrée : créer à partir d'un document. Associez-les une seule fois et ils seront utilisés lors de chaque exécution ultérieure, que ce soit via l'API, le MCP ou l'éditeur, sans frais supplémentaires :

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

Les guides de style s'associent via l'identifiant de version active (obtenu par GET /styleguides/{id}) ; [] permet de les détacher ; ces deux options sont aussi disponibles lors de la création via POST /documents. Côté interface : glossaires, guides de style. La mémoire de traduction ne nécessite aucune association : chaque traduction terminée est indexée et réutilisée automatiquement. Interrogez-la (POST /translation-memory/query, gratuit), alimentez-la depuis un fichier TMX/XLIFF (POST /translation-memory/import, gratuit) ou exportez l'intégralité (GET /translation-memory/export-tmx). Consultez les sections sur la mémoire de traduction et l'import de traductions existantes.

Équipes

Une clé d'équipe est facturée sur le forfait de l'équipe et hérite de ses projets, glossaires, guides de style et de sa mémoire de traduction. Pour créer des documents au sein de l'équipe, transmettez le project_id d'un projet d'équipe (GET /projects ; les projets d'équipe incluent un team_id). Tout le reste est identique à l'usage personnel. La configuration des équipes et des projets s'effectue dans l'application : projets, équipes et invitations.

Exécutions et étapes de révision

L'appel POST /runs traite une seule version linguistique, tandis que POST /group-runs se déploie sur toutes les langues cibles et crée les versions manquantes si nécessaire. Ces deux méthodes proposent une estimation gratuite, acceptent une clé d'idempotence (Idempotency-Key) et peuvent être annulées. Si une étape du workflow est configurée pour attendre une révision, l'exécution est mise en pause : GET /runs/{id} renvoie alors gate_pending: true avec un résumé des éléments identifiés. Côté utilisateur, cette pause se gère via le panneau de révision et la révision guidée ; côté 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"

Une étape de révision ne se débloque jamais d'elle-même : une approbation est nécessaire, qu'elle provienne de votre script, d'un assistant via MCP ou d'une personne dans l'application. Il n'existe aucun paramètre de lancement permettant d'approuver les étapes à l'avance ; si vous souhaitez éviter toute interruption, utilisez un workflow ne comportant aucune étape de révision.

Formats de sortie

L'appel GET /documents/{id}/content?format=<f> sur l'identifiant d'une version linguistique :

L'appel format=strings sur le document maître renvoie toutes les langues en une seule fois, prêtes à être intégrées.

Ne mettre à jour que le delta

Pour les catalogues de chaînes, soumettez à nouveau l'intégralité du fichier actuel ; le serveur se charge de calculer le delta :

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

Les chaînes inchangées conservent leur traduction et leur état de révision ; corriger une seule chaîne ne vous coûte qu'une seule chaîne. (Passez run: {template_id} directement lors de la réimportation pour traiter le delta dans le même appel.) C'est le versant API de la fonction Lancer uniquement les modifications. Pour les documents de type prose dont la source a été modifiée, POST /documents/{id}/resync-source réaligne les blocs : les blocs inchangés conservent leur traduction, les blocs modifiés deviennent obsolètes, et un lancement limité aux mises à jour ne porte que sur ces derniers. La resynchronisation analyse à nouveau le fichier source stocké ; modifiez donc vos sources via le flux d'importation plutôt qu'en retouchant les blocs individuellement.

Assistants IA (MCP)

Le fonctionnement est identique à celui des outils pour agents, à l'adresse https://app.transept.ai/api/public/v1/mcp : me_get → document_create → group_run_estimate / group_run_start → group_run_get → document_content_get. La connexion s'effectue via OAuth (consentement par navigateur, aucune clé à copier-coller ; une clé Bearer suffit pour un usage automatisé). Les outils respectent les autorisations accordées, et toute action entraînant une consommation de mots renvoie d'abord une estimation ; l'assistant doit alors confirmer explicitement. Configuration par client : Connecter votre assistant IA.

FAQ

Les estimations, les réimportations ou les traductions déjà présentes consomment-elles des mots ?

Non. Les estimations sont gratuites et sans effet de bord, la réimportation d'un catalogue ne coûte rien (le calcul du delta s'effectuant côté serveur) et les traductions déjà présentes dans vos fichiers sont intégrées gratuitement en tant que travail terminé. Vous ne consommez des mots que lorsque Transept traduit du contenu pour vous. Les estimations hautes sont ensuite ajustées à la dépense réelle, ce qui libère la réserve inutilisée.

L'automatisation peut-elle contourner mes étapes de révision ?

Non. Une étape de workflow configurée pour une révision met l'exécution en suspens jusqu'à sa validation, qu'elle provienne de votre script (via l'appel du point de terminaison d'approbation) ou d'une personne dans l'application. Si un pipeline doit s'exécuter en toute autonomie de bout en bout, configurez son workflow sans étape de révision : il n'existe aucun paramètre permettant de contourner un point de contrôle que vous avez vous-même instauré.

L'API est-elle disponible avec le forfait Gratuit ?

Oui. Les clés API sont disponibles avec tous les forfaits, y compris l'offre gratuite ; il n'y a aucune barrière d'accès supplémentaire. Votre seule limite est votre solde de mots, tout comme dans l'éditeur, et le quota mensuel du forfait Gratuit s'utilise via l'API de la même manière que partout ailleurs.

Comment traduire mes modèles d'e-mails sans les exporter manuellement ?

Configurez votre plateforme d'e-mailing pour qu'elle envoie une requête vers un déclencheur webhook : le corps du modèle envoyé par POST devient le document, le workflow le traduit, puis l'exportation renvoie la structure HTML d'origine avec les traductions intégrées. Les variables et la syntaxe de templating sont préservées tout au long du processus. Les détails techniques pour chaque plateforme sont disponibles dans le guide de localisation des e-mails.

Où se trouve la référence exhaustive des points de terminaison ?

La référence Swagger interactive, générée à partir de la même spécification OpenAPI que vous pouvez importer dans n8n, Zapier ou un générateur de code (JSON brut). Ce guide constitue le point d'entrée narratif ; la spécification, elle, fait office de contrat.