Waafir
Cette page est une traduction automatique en attente de relecture humaine. Elle peut contenir des erreurs.

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

ChampTypeObligatoireDescription
textstringouiLe texte à traduire, de 1 à 10 000 octets UTF-8.
target_langstringouiCode de la langue cible, p. ex. fr, ar, es.
source_langstringnonCode 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 lorsque source_lang a é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

ChampTypeObligatoireDescription
file_idstringouiL'UUID du fichier.
target_langstringouiCode de la langue cible — l'une des 28 langues dans lesquelles le produit traduit les documents.
retrybooleannonRelance 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_translated ou failed.
  • 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 renvoie enqueued: false et 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

ChampTypeObligatoireDescription
file_idstringouiL'UUID du fichier.
target_langstringouiLa 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, failed ou stale. stale signifie 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 — aucune download_url n'est émise pour elle. Rappelez translate_file pour 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, et download_withheld_reason vaut content_grant_required.
  • download_withheld_reason — présent à la place de download_url lorsque 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é. Relancez translate_file pour 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.