Localiser un catalogue de chaînes via l'API

Le format indexé de Transept est le .tstrings.json : une liste d'unités, chacune dotée d'un id stable, d'une source et, facultativement, d'un context (ce qu'est la chaîne, où elle apparaît), d'une max_length et de placeholders. L'identifiant fait office de contrat : c'est lui qui permet aux traductions de conserver leur identité au fil des réimportations, à l'état de révision de perdurer et à l'exportation d'indexer chaque langue. Ces deux options jouent un rôle concret : le contexte sert de guide au modèle, et la limite de caractères est appliquée via un processus automatique de raccourcissement et de nouvel essai.

Les fichiers CSV, gettext PO et XLIFF sont importés sous forme d'unités indexées identiques via l'application ou le point de terminaison d'importation ; consultez la page fichiers de chaînes pour connaître les correspondances de chaque format. Cet article explique comment piloter ce cycle par programmation, le .tstrings.json étant ici le format natif.

POST /documents/import-strings avec le catalogue au format JSON. La résolution des langues cibles suit un ordre fixe : une mention explicite de target_language / target_languages dans la requête l'emporte ; sinon, ce sont les target_locales de l'en-tête du catalogue qui sont utilisées ; à défaut, l'appel échoue immédiatement avec l'erreur no_target_languages au lieu d'importer un document sans aucune cible. L'appel renvoie un processing_job_id ; interrogez GET /document-jobs/{id} jusqu'à ce que l'importation soit terminée et que vous disposiez des identifiants du document.

Les traductions déjà présentes dans le fichier (targets: {de: "…"}) sont injectées comme traduction active pour chaque chaîne, gratuitement et sans nécessiter de cycle, et alimentent immédiatement votre mémoire de traduction. Le comportement est identique à celui de l'importation de traductions existantes via l'application.

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

Soumettez à nouveau l'intégralité du catalogue actuel à POST /documents/{id}/import-strings, et non une version tronquée. Le serveur compare le catalogue par identifiant d'unité et renvoie les résultats trouvés (added, changed, unchanged, removed) ainsi que les delta_block_ids : les blocs précis nécessitant une intervention, pour chaque langue. Transmettez cet objet tel quel en tant que block_ids d'un cycle groupé et seuls ces blocs seront traduits ; vous pouvez également passer run directement lors de la réimportation pour traiter le delta dans le même appel.

Les unités inchangées conservent leurs traductions ainsi que les révisions déjà effectuées ; c'est le pendant API de la fonction Ne lancer que ce qui a changé. Corriger une seule chaîne dans un catalogue qui en compte des centaines ne vous coûte qu'une seule chaîne.

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

L'appel GET /documents/{id}/content?format=strings sur le document principal renvoie un fichier .tstrings.json contenant les traductions de chaque langue, indexées par identifiant d'unité : un seul appel, prêt à être intégré ou réinjecté dans votre build. Le même point de terminaison propose des rendus par langue (markdown, html, csv, xliff, tmx) si un pipeline nécessite plutôt un format d'échange spécifique ; le tableau complet figure dans Automatiser Transept avec l'API.

Pour les catalogues importés au format CSV, PO ou XLIFF, l'exportation au format d'origine complète les cellules et les entrées de votre propre fichier (une copie à l'octet près de ce que vous avez envoyé, les traductions en plus), afin que le fichier puisse être réintégré directement dans son système d'origine.

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