Waafir
このページは機械翻訳であり、人による確認を待っています。誤りが含まれている可能性があります。

waafir-translate リファレンス

waafir-translate サーバーは、接続された AI クライアントに Waafir の翻訳機能を 2 つの形で提供します。

  • translate_text — テキストの断片を、インラインかつ同期的に翻訳します。
  • translate_file / translate_file_status — データルーム内の文書全体を、AI 翻訳の製品機能と同じ、レイアウトを保持するパイプラインで翻訳します。

接続:https://app.waafir.io/api/mcp/waafir、または領域サーバー https://app.waafir.io/api/mcp/waafir-translate。ツール名はどちらでも同じです。セットアップを参照してください。translate_text と translate_file_status には read スコープ(またはそれ以上)の PAT が必要です。translate_file には write が必要です。文書の翻訳を開始すると永続的なレコードが作成され、有料の翻訳コンピューティングが消費されるためです。

translate_text

短いテキストをターゲット言語に翻訳します。呼び出しは同期的で、テキストを入力してテキストを出力します。ソース言語を省略すると自動検出されます。検出された(または指定した)ソース言語が返されるので、確認できます。

入力

フィールド型必須説明
textstringはい翻訳するテキスト。1~10,000 UTF-8 バイト。
target_langstringはいターゲット言語コード。例:fr、ar、es。
source_langstringいいえソース言語コード。省略すると自動検出されます。

出力

{ translated_text, detected_source_lang }
  • translated_text — ターゲット言語で表現されたテキスト。
  • detected_source_lang — 使用されたソース言語。指定した言語、または source_lang を省略した場合は自動検出された言語です。

要件:有料プランであり、組織の AI 機能が有効になっていること(デフォルトでオン。組織の管理者は 設定 → AI & 統合 でオフにできます)。組織が 1 日の AI 使用量の上限に達した場合や、Waafir がこの機能を一時停止している間も、呼び出しは拒否されます。どちらの理由かはエラーメッセージに示されます。

サイズ制限

このツールは同期処理の経路であるため、text は 1 回の呼び出しにつき 10,000 UTF-8 バイト に制限されています。この制限を超える入力は、暗黙に切り捨てられるのではなく、明確なエラーを返します。文書全体などより大きなコンテンツには、ファイル向けに設計され、レイアウトを保持する文書翻訳機能を使用してください。

translate_file

データルーム内の文書全体の翻訳を開始します。文書翻訳は非同期です。ジョブがキューに登録されるとすぐにこの呼び出しは戻るので、結果は translate_file_status をポーリングして取得します。

入力

フィールド型必須説明
file_idstringはいファイルの UUID。
target_langstringはいターゲット言語コード。製品が文書を翻訳できる 28 言語のいずれか。
retrybooleanいいえ以前に失敗した翻訳を再実行します。完了済みまたは処理中の翻訳では無視されます。

出力

{ file_id, target_lang, language_name, status, enqueued,
  previous_status, delete_with, note? }
  • status — queued、in_progress、already_translated、または failed。
  • enqueued — この呼び出しで実際に処理が開始されたかどうか。必ず確認してください。このツールは完了済みまたは処理中の翻訳を再実行しないため、2 回目の呼び出しは enqueued: false を返し、コストは発生しません。
  • previous_status — この呼び出しの前に翻訳がどの状態だったか。レコードそのものから読み取られます。
  • delete_with — 翻訳を削除してファイルを元の状態に戻す方法。

同じものを二度翻訳しない

製品で「翻訳」を繰り返しクリックする場合とは異なり、translate_file は、同じファイルと言語の翻訳がすでに queued、translating、finalizing のいずれかの状態にある間は再キューイングを拒否します。また、retry: true を明示的に渡さない限り、失敗した翻訳の再実行も拒否します。これは意図的な設計です。毎回再キューイングするリトライループでは、試行のたびに実際の翻訳コンピューティングが消費されてしまいます。

要件:有料プラン、組織の AI 機能が有効になっていること(デフォルトでオン。組織の管理者は 設定 → AI & 統合 でオフにできます)、およびファイルの読み取りとダウンロードの権限。

まだチェック中のファイル。 ファイルが、Waafir のチェックがまだ完了していない新しいアップロードまたは新しいバージョンである場合、translate_file は error.reason: "ACTIVATION_PENDING" とメッセージ This file is still being checked. Try again shortly. を伴う UNAVAILABLE を返します。何もキューに追加されません。少し待ってからもう一度呼び出してください。

translate_file_status

文書翻訳の状態を確認し、準備ができたら翻訳済みファイルの短時間だけ有効なダウンロード URL を取得します。

入力

フィールド型必須説明
file_idstringはいファイルの UUID。
target_langstringはい翻訳をリクエストした言語。

出力

{ file_id, target_lang, language_name, status,
  download_url?, expires_in_seconds?, download_withheld_reason? }
  • status — not_found、queued、translating、finalizing、completed、failed、または stale。stale は、この翻訳が作成された後にソースファイルが以前のバージョンにロールバックされたことを意味します。そのため翻訳はもはや文書と一致せず、提供されなくなり、download_url も発行されません。新しい翻訳を作成するには、もう一度 translate_file を呼び出してください。認識できないステータスは、エラーではなく「未準備」として扱ってください。
  • download_url — 翻訳済みファイルの準備ができていて、安全に提供でき、かつトークンで ドキュメントコンテンツを読む がオンになっている場合(個人用アクセストークン)にのみ含まれます。ブラウザからのダウンロードと同じコピーが提供され、ルームがダウンロードに透かしを入れている場合は透かし付きになり、数分後に期限切れになります。トークンごとに 1 分あたり最大 10 リンクです。
  • ドキュメントコンテンツを読む がオフの場合でも status は取得でき、download_withheld_reason は content_grant_required になります。
  • download_withheld_reason — ファイルの準備はできているものの提供が保留されている場合に、download_url の代わりに含まれます。よくあるケースは、文書が墨消しされているのに、リクエストした翻訳が元の文書から作成されたものである場合です。これを提供すると、墨消しで除去された内容が漏洩してしまいます。translate_file を再実行して、墨消しに対して安全な翻訳を作成してください。

このツールが発行するすべてのダウンロード URL は、ファイルのダウンロードとして組織の監査証跡に記録され、トークンに帰属し、AI クライアントからのものとしてマークされます。製品経由のダウンロードが記録されるのとまったく同じです。