Mansa Platform Docs

Document translation

Upload a document, monitor the translation job in the background, and download the translated file when complete.

POST/v1/translate/file

Request example

JOB=$(curl --fail-with-body "$MANSA_API_BASE_URL/v1/translate/file" \
  -H "Authorization: Bearer $MANSA_API_KEY" \
  -F "file=@financial_report.docx" \
  -F "from=en" \
  -F "to=yor" | jq -r '.data.jobId')

while true; do
  STATUS=$(curl --fail-with-body "$MANSA_API_BASE_URL/v1/translate/file/$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/file/$JOB/download" \
  -H "Authorization: Bearer $MANSA_API_KEY" \
  -o translated.docx

Output

{
  "context": "OK",
  "data": {
    "jobId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "fileType": "docx",
    "segmentCount": 84,
    "message": "File translation started in the background."
  },
  "meta": null
}

Document Translation API

Upload a document file, monitor the translation job in the background, and download the translated document once complete. Supported formats: DOCX, TXT, CSV, and XLSX.


Overview & Flow

Document translation is an asynchronous multi-stage process:

  1. Upload: Submit a file via POST /v1/translate/file (returns HTTP 202 Accepted with a jobId).
  2. Poll Status: Query GET /v1/translate/file/{jobId} until status becomes done, failed, or cancelled.
  3. Download: Fetch the translated document via GET /v1/translate/file/{jobId}/download.
  4. Cancel (Optional): Abort an in-progress job via POST /v1/translate/file/{jobId}/cancel.

[!NOTE] All endpoints require authentication via your API key in the Authorization header:
Authorization: Bearer <YOUR_API_KEY>


1. Initiate Translation

POST /v1/translate/file

Submit a file using multipart/form-data. Alternatively, remote files can be submitted as application/json with a fileUrl.

Multipart Form Fields

FieldTypeRequiredDescription
fileBinaryYesThe document to translate. Supported formats: .docx, .txt, .csv, .xlsx (max 10 MB).
toStringYesTarget language name or ISO code (e.g., yor, ibo, hau, sw, en).
fromStringNoSource language name or code. Defaults to "auto". Explicit source language is strongly recommended.
contextStringNoOptional domain hints, tone, or style guidelines to guide translation.
creativityNumberNoSampling temperature between 0 and 1 (default: 0.3).
max_tokensIntegerNoMaximum token output limit per segment batch (default: 1024).

Example Request (cURL)

curl -X POST https://api.mansa.ai/v1/translate/file \
  -H "Authorization: Bearer mansa_live_..." \
  -F "file=@financial_report.docx" \
  -F "from=en" \
  -F "to=yor" \
  -F "context=Formal financial report for shareholders"

Success Response (202 Accepted)

All successful API responses are wrapped in a standard response envelope (data):

{
  "context": "OK",
  "data": {
    "jobId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "fileType": "docx",
    "segmentCount": 84,
    "message": "File translation started in the background."
  },
  "meta": null
}

2. Check Job Status

GET /v1/translate/file/{jobId}

Poll this endpoint every 2 to 5 seconds to track translation progress.

Response Attributes

FieldTypeDescription
statusStringCurrent job status: "running", "done", "failed", or "cancelled".
fileTypeStringFile extension ("docx", "txt", "csv", "xlsx").
stageString | nullActive processing stage (e.g., "pending", "translating", "completed").
completedSegmentsInteger | nullCount of translated segments processed so far.
totalSegmentsInteger | nullTotal number of extractable segments in the document.
errorString | nullError detail if status is "failed".

Example Response (200 OK)

{
  "context": "OK",
  "data": {
    "status": "running",
    "fileType": "docx",
    "stage": "translating",
    "completedSegments": 42,
    "totalSegments": 84,
    "error": null
  },
  "meta": null
}

3. Download Translated Document

GET /v1/translate/file/{jobId}/download

Downloads the translated binary document once the job reaches "status": "done".

Query Parameters

ParameterTypeRequiredDescription
simpleBoolean / 1NoApplicable to DOCX files only. If 1 or true, generates a simplified rebuilt document if advanced layout retention encounters formatting issues.

HTTP Response Codes

  • 200 OK: Returns the translated document binary stream with appropriate Content-Type and Content-Disposition headers (e.g., financial_report_yor_translated.docx).
  • 202 Accepted: The job is still processing. Returns { "message": "Job is not complete yet" }.
  • 400 Bad Request: The job was cancelled. Returns { "error": "Job was cancelled" }.
  • 422 Unprocessable Entity: The job failed or generated no valid segments. Returns { "error": "<reason>" }.

Example Request

curl -X GET "https://api.mansa.ai/v1/translate/file/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/download" \
  -H "Authorization: Bearer mansa_live_..." \
  --output "financial_report_yor.docx"

4. Cancel a Translation Job

POST /v1/translate/file/{jobId}/cancel

Cancels an in-progress or queued translation job.

Example Response (200 OK)

{
  "context": "OK",
  "data": {
    "message": "File translation job cancelled successfully"
  },
  "meta": null
}

Extraction Rules & Limits

The extraction engine parses incoming files into discrete translation segments:

FormatExtraction RuleLayout & Formatting
CSVFirst column of each non-empty row (header row is detected and preserved).Reconstructed as a CSV table with translated text in column 1.
XLSXFirst column of each non-empty row on the first worksheet.Reconstructed spreadsheet maintaining original row alignment.
TXTOne segment per non-empty line.Reconstructed as UTF-8 text file preserving line breaks.
DOCXExtracted by paragraphs and structural blocks.Paragraph and style formatting preserved on export.

Quotas & Limits

  • Segment Cap: Maximum 1,100 segments per file. Files exceeding this limit are rejected with HTTP 422.
  • DOCX Volume Limit: Capped at 10 DOCX jobs per account per rolling 24 hours.
  • File Size Limit: Maximum 10 MB per uploaded file.

Errors & Status Codes

Errors return RFC-7807 compliant error envelopes:

{
  "type": "about:blank",
  "title": "VALIDATION_ERROR",
  "isError": true,
  "detail": "File size exceeds limit of 10MB.",
  "invalidParams": [],
  "context": ""
}
HTTP StatusError Title (title)Common Causes
400BAD_REQUESTMissing file payload, file > 10 MB, or daily DOCX limit (10 jobs) reached.
401AUTHENTICATION_ERRORMissing, expired, or invalid API key.
404NOT_FOUNDJob ID does not exist or belongs to another account.
422VALIDATION_ERRORUnsupported file extension, missing required to field, or segment limit (> 1,100) exceeded.
500SERVER_ERRORInternal processing error.

Billing & Credits

  • Usage is billed when the translation job completes.
  • Charges are calculated strictly based on the total source character count successfully translated from the extracted file segments (billed at standard translation character pricing).