# MT (Machine Translation)

Translate text between languages with the Machine Translation API.

Translate text between African languages and English using our neural machine translation models.

## Overview

Our MT service provides high-quality translation between supported languages. The models are optimized for African languages including Amharic and Tigrinya.

## Basic Usage

To translate text, send your API key in the request body (not the header):

```curl
curl "https://api.lesan.ai/translate/v1" \
  -d "key=YOUR_API_KEY" \
  -d "text=Hello world!" \
  -d "src_lang=en" \
  -d "tgt_lang=ti"
```

```python
import requests

API_URL = 'https://api.lesan.ai/translate/v1'
API_KEY = 'YOUR_API_KEY'

text = 'Hello world!'
data = {'key': API_KEY, 'text': text, 'src_lang': 'en', 'tgt_lang': 'ti'}

r = requests.post(API_URL, data=data)
print(r.json())
# {'tgt_text': 'ሰላም ዝሰፈኖ ዓለም!'}
```

```javascript
const API_URL = 'https://api.lesan.ai/translate/v1';
const API_KEY = 'YOUR_API_KEY';

const params = new URLSearchParams({
  key: API_KEY,
  text: 'Hello world!',
  src_lang: 'en',
  tgt_lang: 'ti',
});

const response = await fetch(API_URL, {
  method: 'POST',
  body: params,
});

const data = await response.json();
console.log(data);
// { tgt_text: "ሰላም ዝሰፈኖ ዓለም!" }
```

## Request Parameters

Parameters are sent as form data (not JSON):

- **key** (required) — Your API key
- **text** (required) — The text to translate
- **src\_lang** (required) — Source language code
- **tgt\_lang** (required) — Target language code

## Supported Languages

- **en** — English
- **am** — Amharic
- **ti** — Tigrinya

## Translation Directions

You can translate between any supported language pair. Common directions include:

- English ↔ Amharic
- English ↔ Tigrinya
- Amharic ↔ Tigrinya

## Response Format

The API returns the translated text in `tgt_text`:

```json
{
  "tgt_text": "ሰላም ዝሰፈኖ ዓለም!"
}
```

- **tgt\_text** — The translated text in the target language

## Error Handling

Handle common errors when calling the translation API:

```python
import requests

def translate(text, src_lang, tgt_lang):
    r = requests.post(
        "https://api.lesan.ai/translate/v1",
        data={
            "key": "YOUR_API_KEY",
            "text": text,
            "src_lang": src_lang,
            "tgt_lang": tgt_lang
        }
    )

    if r.ok:
        return r.json()["tgt_text"]

    error = r.json().get("error", {})

    if r.status_code == 400:
        raise ValueError(f"Invalid request: {error.get('message', r.text)}")
    elif r.status_code == 401:
        raise PermissionError(f"Authentication failed: {error.get('message', r.text)}")
    elif r.status_code == 429:
        raise Exception(f"Rate limited. Retry after {error.get('retry_after', 1)}s")
    else:
        raise Exception(f"API error ({r.status_code}): {r.text}")

# Usage
try:
    result = translate("Hello, world!", "en", "ti")
    print(result)
except ValueError as e:
    print(f"Fix your request: {e}")
except PermissionError as e:
    print(f"Check your API key: {e}")
```

```javascript
async function translate(text, srcLang, tgtLang) {
  const formData = new URLSearchParams();
  formData.append("key", "YOUR_API_KEY");
  formData.append("text", text);
  formData.append("src_lang", srcLang);
  formData.append("tgt_lang", tgtLang);

  const response = await fetch("https://api.lesan.ai/translate/v1", {
    method: "POST",
    body: formData
  });

  if (response.ok) {
    const data = await response.json();
    return data.tgt_text;
  }

  const errorText = await response.text();

  if (response.status === 400) {
    throw new Error(`Invalid request: ${errorText}`);
  } else if (response.status === 401) {
    throw new Error(`Authentication failed: ${errorText}`);
  } else if (response.status === 429) {
    throw new Error(`Rate limited. Try again later.`);
  } else {
    throw new Error(`API error (${response.status}): ${errorText}`);
  }
}

// Usage
try {
  const result = await translate("Hello, world!", "en", "ti");
  console.log(result);
} catch (err) {
  console.error(err.message);
}
```

## Best Practices

- Keep input text at a reasonable length per request for best performance
- For longer texts, split by paragraph or sentence boundaries
- Cache translations for frequently used text to reduce API calls
- Implement retry logic with exponential backoff for rate limit errors
- Use the correct language codes — see the list above

For detailed API documentation, see the [API Reference](/api-reference). For error handling patterns, see the [Error Codes](/guides/error-codes) reference. For rate limit details, see the [Rate Limits](/guides/rate-limits) guide.