Localize a markdown document over the API
Markdown is the shape most docs, help articles, and CMS content already live in. Send it to the API as-is, run a workflow across your languages, and read the same markdown back per language, with the structure intact.
On this page
How do I send markdown in?
POST /documents with content_type: "markdown" and your target languages. Transept splits the document into blocks and creates one language version per target.
Then estimate and run as in Automate Transept with the API; the run fans across every language version in one call.
# BASE="https://app.transept.ai/api/public/v1"; KEY from Settings → Developer
curl -s -X POST $BASE/documents \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"title": "Getting started", "content_type": "markdown", "source_language": "en",
"target_languages": ["de", "fr"],
"content": "# Getting started\n\nInstall the app, then…"}'
# → { document_id, language_group: [ {id, target_language}, … ] }How do I read translations back?
GET /documents/{id}/content?format=markdown on each language version returns rendered markdown with the structure preserved. The other formats (json for per-block reads, docx, pdf, xliff, csv) are listed in the format table of Automate Transept with the API.
curl -s "$BASE/documents/<de-version-id>/content?format=markdown" \
-H "Authorization: Bearer $KEY"How do I re-translate only what changed?
When the source changes later, re-align instead of re-importing: POST /documents/{id}/resync-source keeps unchanged blocks (and their translations) and marks changed or added blocks stale, and a run with only-updated behavior touches just those. It is the prose twin of the keyed delta in Localize a string catalog over the API; the general behavior is Run only what changed.
# the source changed? re-align, then run only what went stale
curl -s -X POST $BASE/documents/<master>/resync-source \
-H "Authorization: Bearer $KEY"Does the document structure survive translation?
Yes. Headings, lists, links, emphasis, and code spans are preserved through translation and reproduced in the export, so the translated file drops into the same pipeline as the source.
Do I pay again when I re-run an unchanged document?
No. With only-updated behavior, a run touches only blocks whose source changed since the last run. An unchanged document costs nothing to re-run, and a small edit costs a handful of blocks.
Still stuck? Ask Literess in the app, or write to [email protected].