Référence waafir-translate
Le serveur waafir-translate expose la traduction de Waafir à un client IA
connecté, sous deux formes :
translate_text— un extrait de texte, traduit en ligne et de manière synchrone.translate_file/translate_file_status— tout un document d'une salle de données, traduit par le même pipeline préservant la mise en page que celui qu'utilise la fonctionnalité produit Traduction IA.
Connexion : https://app.waafir.io/api/mcp/waafir, ou le serveur de domaine
https://app.waafir.io/api/mcp/waafir-translate ; les noms d'outils sont identiques
sur les deux — voir Configuration. translate_text
et translate_file_status exigent un
PAT de portée read (ou
supérieure) ; translate_file exige write, car lancer la traduction d'un document
crée des enregistrements durables et consomme de la capacité de calcul de traduction
payante.
translate_text
Traduire un texte court dans une langue cible. L'appel est synchrone, avec du texte en entrée et du texte en sortie. Omettez la langue source pour qu'elle soit détectée automatiquement ; la langue source détectée (ou fournie) est renvoyée afin que vous puissiez la confirmer.
Entrées
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
text | string | oui | Le texte à traduire, de 1 à 10 000 octets UTF-8. |
target_lang | string | oui | Code de la langue cible, p. ex. fr, ar, es. |
source_lang | string | non | Code de la langue source. Omettez-le pour une détection automatique. |
Sortie
{ translated_text, detected_source_lang }translated_text— le texte rendu dans la langue cible.detected_source_lang— la langue source utilisée : celle que vous avez fournie, ou celle détectée automatiquement lorsquesource_langa été omis.
Prérequis : une offre payante et les fonctionnalités IA de votre organisation activées (activées par défaut ; un administrateur de l'organisation peut les désactiver dans Paramètres → IA et intégrations). Les appels sont également refusés une fois que votre organisation atteint sa limite quotidienne d'utilisation de l'IA, ou tant que Waafir a mis la fonctionnalité en pause ; le message d'erreur précise lequel des deux.
Limite de taille
Comme l'outil constitue le chemin synchrone, text est limité à 10 000 octets UTF-8 par appel. Une entrée dépassant cette limite renvoie une erreur explicite au
lieu d'être tronquée silencieusement. Pour un contenu plus volumineux — des documents
entiers — utilisez la fonctionnalité de traduction de documents,
conçue pour les fichiers et qui préserve leur mise en page.
translate_file
Lancer la traduction de tout un document d'une salle de données. La traduction de
documents est asynchrone — l'outil répond dès que la tâche est mise en file d'attente,
et vous interrogez translate_file_status pour obtenir le résultat.
Entrées
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
file_id | string | oui | L'UUID du fichier. |
target_lang | string | oui | Code de la langue cible — l'une des 28 langues dans lesquelles le produit traduit les documents. |
retry | boolean | non | Relance une traduction qui a précédemment échoué. Ignoré pour les traductions terminées ou en cours. |
Sortie
{ file_id, target_lang, language_name, status, enqueued,
previous_status, delete_with, note? }status—queued,in_progress,already_translatedoufailed.enqueued— indique si cet appel a réellement lancé un travail. Vérifiez-le : l'outil ne relance pas une traduction déjà terminée ou en cours, donc un second appel renvoieenqueued: falseet ne coûte rien.previous_status— l'état dans lequel se trouvait la traduction avant cet appel, lu dans l'enregistrement lui-même.delete_with— comment supprimer la traduction et ramener le fichier à son original.
Il ne traduit pas deux fois la même chose
Contrairement à un clic répété sur Traduire dans le produit, translate_file refuse de
remettre en file d'attente tant qu'une traduction du même fichier dans la même langue
est déjà queued, translating ou finalizing, et refuse de relancer une traduction
en échec à moins que vous ne transmettiez explicitement retry: true. C'est
délibéré : une boucle de relance qui remettrait en file d'attente à chaque fois
consommerait une réelle capacité de calcul de traduction à chaque passage.
Prérequis : une offre payante, les fonctionnalités IA de votre organisation activées (activées par défaut ; un administrateur de l'organisation peut les désactiver dans Paramètres → IA et intégrations), et la permission de lire et de télécharger le fichier.
Un fichier encore en cours de vérification. Si le fichier est un nouveau
téléversement ou une nouvelle version que Waafir n'a pas fini de vérifier,
translate_file répond UNAVAILABLE avec error.reason: "ACTIVATION_PENDING"
et le message This file is still being checked. Try again shortly. Rien n'est
mis en file d'attente ; rappelez l'outil après un court délai.
translate_file_status
Vérifier l'état de la traduction d'un document et, une fois prête, obtenir une URL de téléchargement à courte durée de vie pour le fichier traduit.
Entrées
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
file_id | string | oui | L'UUID du fichier. |
target_lang | string | oui | La langue dans laquelle la traduction a été demandée. |
Sortie
{ file_id, target_lang, language_name, status,
download_url?, expires_in_seconds?, download_withheld_reason? }status—not_found,queued,translating,finalizing,completed,failedoustale.stalesignifie que le fichier source a été ramené à une version antérieure après la production de cette traduction ; la traduction ne correspond donc plus au document et n'est plus servie — aucunedownload_urln'est émise pour elle. Rappeleztranslate_filepour en produire une nouvelle. Traitez tout statut que vous ne reconnaissez pas comme « pas prêt » plutôt que comme une erreur.download_url— présente uniquement lorsque le fichier traduit est prêt, qu'il peut vous être servi en toute sécurité, et que le jeton a Lire le contenu des documents activé (Jetons d'accès personnels). Elle sert la même copie que le téléchargement depuis le navigateur, filigranée lorsque la salle applique un filigrane aux téléchargements, et expire au bout de quelques minutes. Au plus 10 liens par minute et par jeton.- Sans Lire le contenu des documents, vous obtenez quand même le
status, etdownload_withheld_reasonvautcontent_grant_required. download_withheld_reason— présent à la place dedownload_urllorsque le fichier est prêt mais retenu. Le cas courant : le document a été caviardé, et la traduction que vous demandez a été produite à partir de l'original ; la servir divulguerait donc du contenu que le caviardage a supprimé. Relanceztranslate_filepour produire une traduction compatible avec le caviardage.
Chaque URL de téléchargement émise par cet outil est consignée dans la piste d'audit de votre organisation comme un téléchargement de fichier, attribuée au jeton et marquée comme provenant d'un client IA — exactement comme l'est un téléchargement effectué via le produit.