Referencia de waafir-translate
El servidor waafir-translate expone la traducción de Waafir a un cliente
de IA conectado, de dos formas:
translate_text— un fragmento de texto, traducido en línea y de forma síncrona.translate_file/translate_file_status— un documento completo de una sala de datos, traducido mediante el mismo proceso que conserva el diseño y que usa la función de producto Traducción con IA.
Conexión: https://app.waafir.io/api/mcp/waafir, o el servidor de área
https://app.waafir.io/api/mcp/waafir-translate; los nombres de las
herramientas son los mismos en ambos — consulte
Configuración. translate_text y
translate_file_status requieren un
PAT con alcance read (o
superior); translate_file requiere write, porque iniciar la traducción de
un documento crea registros duraderos y consume capacidad de traducción de
pago.
translate_text
Traduce un texto breve a un idioma de destino. La llamada es síncrona: entra texto y sale texto. Omita el idioma de origen para que se detecte automáticamente; se devuelve el idioma de origen detectado (o proporcionado) para que pueda confirmarlo.
Entradas
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
text | string | sí | El texto que se va a traducir, de 1 a 10.000 bytes UTF-8. |
target_lang | string | sí | Código del idioma de destino, p. ej. fr, ar, es. |
source_lang | string | no | Código del idioma de origen. Omítalo para la detección automática. |
Salida
{ translated_text, detected_source_lang }translated_text— el texto expresado en el idioma de destino.detected_source_lang— el idioma de origen que se usó: el que usted proporcionó, o el detectado automáticamente cuando se omitiósource_lang.
Requisitos: un plan de pago y las funciones de IA de su organización habilitadas (activadas por defecto; un administrador de la organización puede desactivarlas en Configuración → IA e Integraciones). Las llamadas también se rechazan cuando su organización alcanza su límite diario de uso de IA, o mientras Waafir haya pausado la función; el mensaje de error indica cuál de los dos casos se da.
Límite de tamaño
Como esta herramienta es la vía síncrona, text está limitado a 10.000 bytes UTF-8 por llamada. Una entrada que supere ese límite devuelve un error claro
en lugar de truncarse en silencio. Para contenidos más grandes — documentos
completos — use la
función de traducción de documentos, que
está diseñada para archivos y conserva su diseño.
translate_file
Inicia la traducción de un documento completo de una sala de datos. La
traducción de documentos es asíncrona: la llamada responde en cuanto el
trabajo queda en cola, y usted consulta translate_file_status para obtener
el resultado.
Entradas
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
file_id | string | sí | El UUID del archivo. |
target_lang | string | sí | Código del idioma de destino: uno de los 28 idiomas a los que el producto traduce documentos. |
retry | boolean | no | Vuelve a ejecutar una traducción que falló anteriormente. Se ignora para traducciones completadas o en curso. |
Salida
{ file_id, target_lang, language_name, status, enqueued,
previous_status, delete_with, note? }status—queued,in_progress,already_translatedofailed.enqueued— si esta llamada realmente inició el trabajo. Compruébelo: la herramienta no vuelve a ejecutar una traducción que ya está completada o en curso, por lo que una segunda llamada devuelveenqueued: falsey no cuesta nada.previous_status— el estado en que se encontraba la traducción antes de esta llamada, leído del propio registro.delete_with— cómo eliminar la traducción y devolver el archivo a su original.
No traduce dos veces lo mismo
A diferencia de hacer clic varias veces en Traducir en el producto,
translate_file se niega a volver a poner en cola mientras una traducción del
mismo archivo y el mismo idioma ya está en queued, translating o
finalizing, y se niega a volver a ejecutar una traducción fallida salvo
que pase explícitamente retry: true. Es deliberado: un bucle de reintentos
que volviera a poner en cola cada vez consumiría capacidad de traducción real
en cada pasada.
Requisitos: un plan de pago, las funciones de IA de su organización habilitadas (activadas por defecto; un administrador de la organización puede desactivarlas en Configuración → IA e Integraciones) y permiso para leer y descargar el archivo.
Un archivo que aún se está comprobando. Si el archivo es una subida o
versión nueva que Waafir aún no ha terminado de comprobar, translate_file
responde UNAVAILABLE con error.reason: "ACTIVATION_PENDING" y el mensaje
This file is still being checked. Try again shortly. No se pone nada en cola;
vuelva a llamar tras una breve espera.
translate_file_status
Comprueba la traducción de un documento y, cuando está lista, obtiene una URL de descarga de corta duración para el archivo traducido.
Entradas
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
file_id | string | sí | El UUID del archivo. |
target_lang | string | sí | El idioma en que se solicitó la traducción. |
Salida
{ file_id, target_lang, language_name, status,
download_url?, expires_in_seconds?, download_withheld_reason? }status—not_found,queued,translating,finalizing,completed,failedostale.stalesignifica que el archivo de origen se revirtió a una versión anterior después de producirse esta traducción, por lo que la traducción ya no coincide con el documento y ya no se sirve: no se emite ningúndownload_urlpara ella. Vuelva a llamar atranslate_filepara producir una nueva. Trate cualquier estado que no reconozca como "no está lista" en lugar de como un error.download_url— solo está presente cuando el archivo traducido está listo, es seguro servírselo y el token tiene Leer contenido de documentos activado (Tokens de acceso personal). Sirve la misma copia que le da la descarga desde el navegador, con marca de agua cuando la sala aplica marca de agua a las descargas, y vence a los pocos minutos. Como máximo 10 enlaces por minuto y por token.- Sin Leer contenido de documentos, sigue obteniendo el
status, ydownload_withheld_reasonescontent_grant_required. download_withheld_reason— presente en lugar dedownload_urlcuando el archivo está listo pero retenido. El caso habitual: al documento se le ha aplicado la supresión de datos, y la traducción que pide se produjo a partir del original, por lo que servirla filtraría contenido que la supresión de datos eliminó. Vuelva a ejecutartranslate_filepara producir una traducción segura respecto a la supresión de datos.
Cada URL de descarga que emite esta herramienta queda registrada en el registro de auditoría de su organización como una descarga de archivo, atribuida al token y marcada como procedente de un cliente de IA — exactamente igual que se registra una descarga a través del producto.