waafir-translate reference

The waafir-translate server exposes Waafir's translation to a connected AI client, in two shapes:

• translate_text — a snippet of text, translated inline and synchronously.
• translate_file / translate_file_status — a whole document in a data room, translated by the same layout-preserving pipeline the AI Translation product feature uses.

Connection: https://app.waafir.io/api/mcp/waafir-translate — see Setup. translate_text and translate_file_status need a read-scope (or higher) PAT; translate_file needs write, because starting a document translation creates durable records and spends paid translation compute.

translate_text

Translate a short text into a target language. The call is synchronous and text-in / text-out. Omit the source language to have it detected automatically; the detected (or supplied) source is returned so you can confirm it.

Inputs

Output

{ translated_text, detected_source_lang }

• translated_text — the text rendered in the target language.
• detected_source_lang — the source language that was used: the one you supplied, or the one auto-detected when source_lang was omitted.

Size limit

Because the tool is the synchronous path, text is limited to 10,000 UTF-8 bytes per call. Input over that limit returns a clear error rather than being silently truncated. For larger content — whole documents — use the document translation feature, which is built for files and preserves their layout.

translate_file

Start translating a whole document in a data room. Document translation is asynchronous — this returns as soon as the job is queued, and you poll translate_file_status for the result.

Inputs

Output

{ file_id, target_lang, language_name, status, enqueued,
  previous_status, delete_with, note? }

• status — queued, in_progress, already_translated, or failed.
• enqueued — whether this call actually started work. Check it: the tool will not re-run a translation that is already completed or in flight, so a second call returns enqueued: false and costs nothing.
• previous_status — the state the translation was in before this call, read from the record itself.
• delete_with — how to remove the translation and return the file to its original.

It will not translate the same thing twice

Unlike clicking Translate repeatedly in the product, translate_file refuses to re-queue while a translation for the same file and language is already queued, translating or finalizing, and it refuses to re-run a failed translation unless you explicitly pass retry: true. This is deliberate: a retry loop that re-queued each time would spend real translation compute on every pass.

Requirements: a paid plan, your organization's AI features enabled, and permission to read and download the file.

translate_file_status

Check a document translation and, once it is ready, get a short-lived download URL for the translated file.

Inputs

Output

{ file_id, target_lang, language_name, status,
  download_url?, expires_in_seconds?, download_withheld_reason? }

• status — not_found, queued, translating, finalizing, completed, failed, or stale. stale means the source file was rolled back to an earlier version after this translation was produced, so the translation no longer matches the document and is no longer served — no download_url is issued for it. Call translate_file again to produce a fresh one. Treat any status you do not recognise as "not ready" rather than as an error.
• download_url — present only when the translated file is ready and it is safe to serve to you. The URL expires after a few minutes.
• download_withheld_reason — present instead of download_url when the file is ready but withheld. The common case: the document has been redacted, and the translation you are asking for was produced from the original, so serving it would leak content the redaction removed. Re-run translate_file to produce a redaction-safe translation.

Every download URL this tool issues is recorded in your organization's audit trail as a file download, attributed to the token and marked as coming from an AI client — exactly as a download through the product is recorded.