Translate

The main endpoint for translating text between supported languages. Send the full language name, such as English and Swahili. Codes such as en and sw also work.

Authenticate with a Mansa API key in the Authorization header. See Authentication.

Request parameters

Send either text (single string) or segments (sync multi-segment), not both.

Response

Single-string requests return data.translation:

{
  "context": "ok",
  "data": {
    "translation": "Habari za asubuhi"
  }
}

Sync segments requests return data.segments (and optional from / to):

{
  "context": "ok",
  "data": {
    "segments": [
      {
        "text": "Hello",
        "translated_text": "Hujambo",
        "id": "1"
      }
    ],
    "from": "English",
    "to": "Swahili"
  }
}

Sync vs async

Document translation

For files, use the async Document translation API. Upload a file, poll job status, and download the translated document.

Batch translation

For more than 10 short strings, use Batch translation. Send up to 100 segments in one async job and poll until results are ready.

Multiple segments

Use segments when you need up to 10 translations in one synchronous response. Each optional id is echoed in the response.

curl --fail-with-body "$MANSA_API_BASE_URL/v1/translate" \
  -H "Authorization: Bearer $MANSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "English",
  "to": "Swahili",
  "segments": [
    {
      "id": "1",
      "text": "Hello"
    },
    {
      "id": "2",
      "text": "How are you?"
    }
  ]
}'

{
  "context": "ok",
  "data": {
    "segments": [
      {
        "id": "1",
        "text": "Hello",
        "translated_text": "Hujambo"
      },
      {
        "id": "2",
        "text": "How are you?",
        "translated_text": "Habari yako?"
      }
    ],
    "from": "English",
    "to": "Swahili"
  }
}

Glossary

Pass inline glossary entries to prefer specific term translations for this request. Saved glossary IDs (glossaryId) are not supported on the public API; send glossary inline or use Batch translation for the same inline shape on async jobs.

curl --fail-with-body "$MANSA_API_BASE_URL/v1/translate" \
  -H "Authorization: Bearer $MANSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Hello",
  "from": "English",
  "to": "Swahili",
  "glossary": [
    {
      "term": "hello",
      "translation": "hujambo"
    }
  ]
}'

{
  "context": "ok",
  "data": {
    "translation": "Hujambo"
  }
}

Tone

Use tone when you need a specific register. Omit it for the default natural style.

curl --fail-with-body "$MANSA_API_BASE_URL/v1/translate" \
  -H "Authorization: Bearer $MANSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Please send the invoice today.",
  "from": "English",
  "to": "Yoruba",
  "tone": "formal"
}'

{
  "context": "ok",
  "data": {
    "translation": "Jọwọ fi ìwé àjọ-owó ránṣẹ lónìí."
  }
}

Context

Pass context when a word could mean more than one thing.

curl --fail-with-body "$MANSA_API_BASE_URL/v1/translate" \
  -H "Authorization: Bearer $MANSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "The bank is closed.",
  "from": "English",
  "to": "Hausa",
  "tone": "precise",
  "context": "A river bank, not a financial institution."
}'

{
  "context": "ok",
  "data": {
    "translation": "Gabar kogin ta rufe."
  }
}

Service status

GET /v1/translate/status returns { "status": "ok" } when the translation backend is available. Requires the same Bearer authentication as other /v1 endpoints.

curl --fail-with-body "$MANSA_API_BASE_URL/v1/translate/status" \
  -H "Authorization: Bearer $MANSA_API_KEY"

{
  "context": "ok",
  "data": {
    "status": "ok"
  }
}

Supported languages

Stable languages

Beta languages

Stable languages support translation between one another. Beta coverage is primarily available between English and the beta language.

Errors and billing

Unsupported languages and tones return invalid_request. Insufficient Mansa Credits return insufficient_credit. Successful translations debit Mansa Credits according to source character count (including all segment text when using segments). The rate is $0.10 per 1K characters ($100 per 1M) — see Pricing.