Mansa Platform Docs
Console

Document translation

Upload a document, poll job status, and download the translated file when complete.

POST/v1/translate/documents

Request example

JOB=$(curl --fail-with-body "$MANSA_API_BASE_URL/v1/translate/documents" \
  -H "Authorization: Bearer $MANSA_API_KEY" \
  -F "file=@source.docx" \
  -F "from=English" \
  -F "to=Swahili" | jq -r '.data.id')

while true; do
  STATUS=$(curl --fail-with-body "$MANSA_API_BASE_URL/v1/translate/documents/$JOB" \
    -H "Authorization: Bearer $MANSA_API_KEY" | jq -r '.data.status')
  if [ "$STATUS" = "done" ]; then break; fi
  if [ "$STATUS" = "failed" ] || [ "$STATUS" = "cancelled" ]; then exit 1; fi
  sleep 4
done

curl --fail-with-body "$MANSA_API_BASE_URL/v1/translate/documents/$JOB/content" \
  -H "Authorization: Bearer $MANSA_API_KEY" \
  -o translated.docx

Output

{
  "context": "ok",
  "data": {
    "id": "7c4e2b1a-9f3d-4a8e-b2c1-0d9e8f7a6b5c",
    "status": "running",
    "file_type": "docx",
    "segment_count": 42,
    "source_chars": 12840
  }
}

Upload a file, poll until the job finishes, then download the translated file. Supported formats: DOCX, TXT, CSV, and XLSX.

Flow

  1. POST /v1/translate/documents with multipart/form-data (returns 202 and a job id)
  2. GET /v1/translate/documents/{id} until status is done, failed, or cancelled
  3. GET /v1/translate/documents/{id}/content to download the translated file

Use POST /v1/translate/documents/{id}/cancel to stop a running job.

Upload fields

FieldTypeRequiredDescription
filefileYesDOCX, TXT, CSV, or XLSX (max 10 MB)
fromstringYesSource language name or code
tostringYesTarget language name or code
contextstringNoOptional hints about tone, domain, or terminology
glossarystringNoJSON array of { "term", "translation" } objects

Auto-detect is not supported for the source language.

Extraction rules

FormatSegments
CSV / XLSXFirst column of each non-empty row
TXTOne segment per non-empty line
DOCXParagraphs (layout preserved when possible on download)

Maximum 1,100 segments per file. DOCX uploads are limited to 10 jobs per account per rolling 24 hours.

Status response

Poll GET /v1/translate/documents/{id} every few seconds. While status is running, stage may be translating or assembling, and completed_segments / total_segments show progress when available.

Download

GET /v1/translate/documents/{id}/content returns the translated file when status is done. Add ?simple=1 for a simplified DOCX rebuild when layout export is unavailable.

If the job is still running, the endpoint returns 202 with a JSON body.

Supported languages

Document translation uses the same language catalog as Translate. Send explicit source and target languages.

Errors and billing

Unsupported file types, missing languages, and segment limits return invalid_request. Insufficient Mansa Credits return insufficient_credit.

Usage is charged when the job completes, based on the source character count extracted from the file (same per-character rate as text translation). See Pricing.