Waafir
Esta página é uma tradução automática pendente de revisão humana. Pode conter erros.

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

CampoTipoObrigatórioDescrição
textstringsimO texto a traduzir, de 1 a 10.000 bytes UTF-8.
target_langstringsimCódigo do idioma de destino, por exemplo fr, ar, es.
source_langstringnãoCó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 quando source_lang foi 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

CampoTipoObrigatórioDescrição
file_idstringsimO UUID do arquivo.
target_langstringsimCódigo do idioma de destino — um dos 28 idiomas para os quais o produto traduz documentos.
retrybooleannãoExecuta 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_translated ou failed.
  • 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 retorna enqueued: false e 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

CampoTipoObrigatórioDescrição
file_idstringsimO UUID do arquivo.
target_langstringsimO 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, failed ou stale. stale significa 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 — nenhuma download_url é emitida para ela. Chame translate_file novamente 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, e download_withheld_reason é content_grant_required.
  • download_withheld_reason — presente em vez de download_url quando 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. Execute translate_file novamente 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.