Waafir
Esta página es una traducción automática pendiente de revisión humana. Puede contener errores.

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

CampoTipoObligatorioDescripción
textstringsíEl texto que se va a traducir, de 1 a 10.000 bytes UTF-8.
target_langstringsíCódigo del idioma de destino, p. ej. fr, ar, es.
source_langstringnoCó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

CampoTipoObligatorioDescripción
file_idstringsíEl UUID del archivo.
target_langstringsíCódigo del idioma de destino: uno de los 28 idiomas a los que el producto traduce documentos.
retrybooleannoVuelve 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_translated o failed.
  • 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 devuelve enqueued: false y 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

CampoTipoObligatorioDescripción
file_idstringsíEl UUID del archivo.
target_langstringsí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, failed o stale. stale significa 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ún download_url para ella. Vuelva a llamar a translate_file para 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, y download_withheld_reason es content_grant_required.
  • download_withheld_reason — presente en lugar de download_url cuando 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 ejecutar translate_file para 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.