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
短いテキストをターゲット言語に翻訳します。呼び出しは同期的で、テキストを入力してテキストを出力します。ソース言語を省略すると自動検出されます。検出された(または指定した)ソース言語が返されるので、確認できます。
入力
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
text | string | はい | 翻訳するテキスト。1~10,000 UTF-8 バイト。 |
target_lang | string | はい | ターゲット言語コード。例:fr、ar、es。 |
source_lang | string | いいえ | ソース言語コード。省略すると自動検出されます。 |
出力
{ 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_id | string | はい | ファイルの UUID。 |
target_lang | string | はい | ターゲット言語コード。製品が文書を翻訳できる 28 言語のいずれか。 |
retry | boolean | いいえ | 以前に失敗した翻訳を再実行します。完了済みまたは処理中の翻訳では無視されます。 |
出力
{ 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_id | string | はい | ファイルの UUID。 |
target_lang | string | はい | 翻訳をリクエストした言語。 |
出力
{ 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 クライアントからのものとしてマークされます。製品経由のダウンロードが記録されるのとまったく同じです。