waafir-translate 참조
waafir-translate 서버는 연결된 AI 클라이언트에 Waafir의 번역 기능을 두 가지 형태로 제공합니다.
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 & 통합에서 끌 수 있습니다). 조직이 일일 AI 사용 한도에 도달했거나 Waafir가 해당 기능을 일시 중지한 동안에도 호출이 거부되며, 오류 메시지에 어떤 경우인지 표시됩니다.
크기 제한
이 도구는 동기식 경로이므로 text는 호출당 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— 이번 호출이 실제로 작업을 시작했는지 여부. 반드시 확인하세요. 이 도구는 이미 완료되었거나 진행 중인 번역을 다시 실행하지 않으므로, 두 번째 호출은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— 번역된 파일이 준비되었고, 안전하게 제공할 수 있으며, 그리고 토큰에 문서 내용 읽기가 켜져 있는 경우(개인 액세스 토큰)에만 포함됩니다. 브라우저 다운로드로 받는 것과 동일한 사본을 제공하며, 데이터룸이 다운로드에 워터마크를 적용하는 경우 워터마크가 적용되고, 몇 분 후에 만료됩니다. 토큰당 분당 최대 10개의 링크를 받을 수 있습니다.- 문서 내용 읽기가 없어도
status는 받을 수 있으며,download_withheld_reason은content_grant_required가 됩니다. download_withheld_reason— 파일은 준비되었지만 제공이 보류된 경우download_url대신 포함됩니다. 흔한 경우는 문서가 가림 처리되었는데 요청한 번역이 원본 문서로부터 생성된 경우로, 이를 제공하면 가림 처리로 제거된 내용이 유출됩니다.translate_file을 다시 실행하여 가림 처리에 안전한 번역을 생성하세요.
이 도구가 발급하는 모든 다운로드 URL은 조직의 감사 기록에 파일 다운로드로 기록되며, 해당 토큰에 귀속되고 AI 클라이언트에서 발생한 것으로 표시됩니다. 제품을 통한 다운로드가 기록되는 방식과 정확히 같습니다.