> ## Documentation Index
> Fetch the complete documentation index at: https://developers.namuai-lab.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Traduction

> Du haoussa vers le français et du français vers le haoussa, à partir d’un texte ou directement de la parole, avec la traduction dite à voix haute si vous le souhaitez.

6 min

Traduire entre le haoussa et le français

## Vue d’ensemble

`POST /v1/translate` traduit entre le **haoussa et le français**, dans les deux sens. Il reçoit un texte ou un enregistrement, et peut aussi renvoyer la traduction parlée : une seule requête transforme ainsi une note vocale en haoussa en audio en français.

* **Modèle :** `translation` (bêta)
* **Sens :** `ha → fr` et `fr → ha`
* **Entrée :** du texte en JSON (jusqu’à 2 000 caractères), ou de l’audio comme pour la [transcription](https://developers.namuai-lab.com/fr/capabilities/speech-to-text.md#audio-pris-en-charge)
* **Ce qui est compté :** pour un texte, le nombre de caractères ÷ 15, en secondes ; pour l’audio, la durée envoyée ; plus la traduction parlée si vous la demandez

> [!NOTE]
>
> La traduction est rédigée par **Google Gemini via OpenRouter**, qui reçoit le texte à traduire (et, pour le français parlé, l’enregistrement, afin de le mettre par écrit). Prévenez vos utilisateurs si leurs messages partent chez un tiers. La transcription et la synthèse vocale tournent sur les propres modèles de Namu.

## Traduire un texte

Envoyez du JSON. `target` est la langue que vous voulez ; `source` est l’autre, sauf indication contraire.

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.namuai-lab.com/v1/translate \
  -H "Authorization: Bearer $NAMU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Ina kwana? Yau za a yi zafi sosai.", "source": "ha", "target": "fr"}'
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
import requests

response = requests.post(
    "https://api.namuai-lab.com/v1/translate",
    headers={"Authorization": f"Bearer {os.environ['NAMU_API_KEY']}"},
    json={"text": "Ina kwana? Yau za a yi zafi sosai.", "source": "ha", "target": "fr"},
    timeout=120,
)
print(response.json()["text"])
```

```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await fetch("https://api.namuai-lab.com/v1/translate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NAMU_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ text: "Ina kwana? Yau za a yi zafi sosai.", source: "ha", target: "fr" }),
});
const { text } = await response.json();
```

```json Réponse theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "model": "translation",
  "source": "ha",
  "target": "fr",
  "source_text": "Ina kwana? Yau za a yi zafi sosai.",
  "text": "Bonjour ! Il va faire très chaud aujourd'hui.",
  "characters": 34,
  "audio": null
}
```

> [!NOTE]
>
> Les traductions montrées dans cette documentation illustrent la forme de la réponse. Vos résultats varieront selon le texte.

## Traduire la parole

Envoyez l’enregistrement dans `file`. L’API écrit ce qui a été dit (`source_text`), puis le traduit (`text`) :

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.namuai-lab.com/v1/translate \
  -H "Authorization: Bearer $NAMU_API_KEY" \
  -F file=@question.ogg \
  -F source=ha \
  -F target=fr
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
with open("question.ogg", "rb") as audio:
    response = requests.post(
        "https://api.namuai-lab.com/v1/translate",
        headers={"Authorization": f"Bearer {os.environ['NAMU_API_KEY']}"},
        files={"file": audio},
        data={"source": "ha", "target": "fr"},
        timeout=300,
    )
result = response.json()
print(result["source_text"], "→", result["text"])
```

```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const form = new FormData();
form.append("file", new Blob([await readFile("question.ogg")]), "question.ogg");
form.append("source", "ha");
form.append("target", "fr");

const result = await fetch("https://api.namuai-lab.com/v1/translate", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.NAMU_API_KEY}` },
  body: form,
}).then((r) => r.json());
```

Si aucune parole n’est trouvée dans l’enregistrement, la réponse est `422 nothing_heard`.

## Recevoir la traduction parlée

Ajoutez `include_audio` et la réponse contient un champ `audio` : la traduction parlée, en WAV base64 (24 kHz, mono). Avec du JSON, mettez-le dans le corps ; avec de l’audio, en champ de formulaire ou en paramètre de requête.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "text": "Bonjour, comment allez-vous ?", "source": "fr", "target": "ha", "include_audio": true }
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import base64

audio = base64.b64decode(response.json()["audio"])
open("translation.wav", "wb").write(audio)
```

## Requête

**text** `string`

Le texte à traduire, jusqu’à 2 000 caractères. Envoyez ce champ **ou** `file`.

**file** `file`

Un enregistrement à traduire. Envoyez ce champ **ou** `text`.

**target** `string` (default: fr)

La langue vers laquelle traduire : `ha` ou `fr`.

**source** `string`

La langue de l’entrée : `ha` ou `fr`. Par défaut, la langue qui n’est pas `target`.

**include\_audio** `boolean` (default: false)

Renvoyer aussi la traduction parlée, en WAV base64.

## Bonnes pratiques

* **Traduisez des phrases entières.** Le modèle s’appuie sur la phrase autour d’un mot pour en choisir le sens ; un fragment perd ce contexte.
* **Montrez les deux textes quand c’est important.** `source_text` permet au lecteur de vérifier ce qui a été compris avant de se fier à la traduction.
* **Gardez une personne dans la boucle quand l’enjeu est élevé.** Les messages médicaux, juridiques et financiers méritent une vérification humaine avant d’arriver aux gens.

## Limites

* Haoussa et français uniquement. Le zarma ⇄ français n’est pas encore dans l’API (`400 unsupported_pair`).
* 2 000 caractères de texte, ou 25 Mo et 5 minutes d’audio, par requête.

## Voir aussi

> [card] [Construire un interprète](https://developers.namuai-lab.com/fr/tutorials/hausa-french-interpreter.md)
>
> Tutoriel

> [card] [Transcription](https://developers.namuai-lab.com/fr/capabilities/speech-to-text.md)
>
> Les mêmes règles pour l’audio

> [card] [Référence de l’API](https://developers.namuai-lab.com/fr/api-reference/translation/create-translation.md)
>
> POST /v1/translate


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.