Referência do waafir-translate
O servidor waafir-translate disponibiliza a tradução do Waafir para um cliente
de IA conectado, em dois formatos:
translate_text— um trecho de texto, traduzido em linha e de forma síncrona.translate_file/translate_file_status— um documento inteiro em uma sala de dados, traduzido pelo mesmo pipeline com preservação de layout que o recurso Tradução por IA do produto usa.
Conexão: https://app.waafir.io/api/mcp/waafir ou o servidor da área
https://app.waafir.io/api/mcp/waafir-translate; os nomes das ferramentas são os mesmos em ambos — consulte
Configuração. translate_text e
translate_file_status exigem um
PAT com escopo read (ou superior); translate_file exige
write, porque iniciar a tradução de um documento cria registros duradouros e
consome capacidade de tradução paga.
translate_text
Traduz um texto curto para um idioma de destino. A chamada é síncrona e do tipo texto de entrada / texto de saída. Omita o idioma de origem para que ele seja detectado automaticamente; o idioma de origem detectado (ou informado) é retornado para que você possa confirmá-lo.
Entradas
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
text | string | sim | O texto a traduzir, de 1 a 10.000 bytes UTF-8. |
target_lang | string | sim | Código do idioma de destino, por exemplo fr, ar, es. |
source_lang | string | não | Código do idioma de origem. Omita para detecção automática. |
Saída
{ translated_text, detected_source_lang }translated_text— o texto no idioma de destino.detected_source_lang— o idioma de origem que foi usado: o que você informou ou o detectado automaticamente quandosource_langfoi omitido.
Requisitos: um plano pago e os recursos de IA da sua organização ativados (ativados por padrão; um administrador da organização pode desativá-los em Configurações → IA e Integrações). As chamadas também são recusadas quando sua organização atinge o limite diário de uso de IA ou enquanto o Waafir mantém o recurso pausado; a mensagem de erro indica qual é o caso.
Limite de tamanho
Como a ferramenta é o caminho síncrono, text é limitado a 10.000 bytes UTF-8 por chamada. Uma entrada acima desse limite retorna um erro claro, em vez de ser
truncada silenciosamente. Para conteúdos maiores — documentos inteiros — use o
recurso de tradução de documentos, criado para
arquivos e que preserva o layout deles.
translate_file
Inicia a tradução de um documento inteiro em uma sala de dados. A tradução de documentos é
assíncrona — a chamada retorna assim que o job é colocado na fila, e você consulta
translate_file_status para obter o resultado.
Entradas
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
file_id | string | sim | O UUID do arquivo. |
target_lang | string | sim | Código do idioma de destino — um dos 28 idiomas para os quais o produto traduz documentos. |
retry | boolean | não | Executa novamente uma tradução que falhou anteriormente. Ignorado para traduções concluídas ou em andamento. |
Saída
{ file_id, target_lang, language_name, status, enqueued,
previous_status, delete_with, note? }status—queued,in_progress,already_translatedoufailed.enqueued— se esta chamada de fato iniciou o trabalho. Verifique-o: a ferramenta não executa novamente uma tradução já concluída ou em andamento, portanto uma segunda chamada retornaenqueued: falsee não tem custo.previous_status— o estado em que a tradução estava antes desta chamada, lido do próprio registro.delete_with— como remover a tradução e devolver o arquivo ao seu original.
Ela não traduz a mesma coisa duas vezes
Ao contrário de clicar em Traduzir repetidamente no produto, translate_file se recusa a
colocar novamente na fila enquanto uma tradução do mesmo arquivo e idioma já está
queued, translating ou finalizing, e se recusa a executar novamente uma tradução que falhou,
a menos que você passe explicitamente retry: true. Isso é proposital: um
loop de novas tentativas que colocasse o job na fila a cada vez consumiria capacidade real de tradução
em cada passagem.
Requisitos: um plano pago, os recursos de IA da sua organização ativados (ativados por padrão; um administrador da organização pode desativá-los em Configurações → IA e Integrações) e permissão para ler e baixar o arquivo.
Um arquivo que ainda está sendo verificado. Se o arquivo for um novo envio
ou uma nova versão que o Waafir ainda não terminou de verificar,
translate_file responde UNAVAILABLE com error.reason: "ACTIVATION_PENDING"
e a mensagem This file is still being checked. Try again shortly. Nada é
colocado na fila; chame de novo após uma breve espera.
translate_file_status
Verifica uma tradução de documento e, quando ela estiver pronta, obtém uma URL de download de curta duração para o arquivo traduzido.
Entradas
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
file_id | string | sim | O UUID do arquivo. |
target_lang | string | sim | O idioma em que a tradução foi solicitada. |
Saída
{ file_id, target_lang, language_name, status,
download_url?, expires_in_seconds?, download_withheld_reason? }status—not_found,queued,translating,finalizing,completed,failedoustale.stalesignifica que o arquivo de origem foi revertido para uma versão anterior depois que esta tradução foi produzida; assim, a tradução não corresponde mais ao documento e deixa de ser servida — nenhumadownload_urlé emitida para ela. Chametranslate_filenovamente para produzir uma nova. Trate qualquer status que você não reconheça como "não pronto", e não como um erro.download_url— presente somente quando o arquivo traduzido está pronto, é seguro servi-lo a você e o token tem Ler conteúdo do documento ativado (Tokens de acesso pessoal). Ela serve a mesma cópia que o download pelo navegador fornece, com marca d'água quando a sala aplica marca d'água aos downloads, e expira após alguns minutos. No máximo 10 links por minuto por token.- Sem Ler conteúdo do documento, você ainda recebe o
status, edownload_withheld_reasonécontent_grant_required. download_withheld_reason— presente em vez dedownload_urlquando o arquivo está pronto, mas retido. O caso mais comum: o documento foi tarjado, e a tradução que você está solicitando foi produzida a partir do original; servi-la vazaria conteúdo que o tarjamento removeu. Executetranslate_filenovamente para produzir uma tradução segura em relação ao tarjamento.
Toda URL de download emitida por esta ferramenta é registrada na trilha de auditoria da sua organização como um download de arquivo, atribuído ao token e marcado como proveniente de um cliente de IA — exatamente como é registrado um download feito pelo produto.