مرجع waafir-translate
يتيح الخادم waafir-translate ميزة الترجمة في Waafir لعميل ذكاء اصطناعي متصل،
بشكلين:
translate_text— مقطع نصي يُترجم مباشرةً وبشكل متزامن.translate_file/translate_file_status— مستند كامل في غرفة بيانات، يُترجم عبر مسار المعالجة نفسه المحافظ على التخطيط الذي تستخدمه ميزة الترجمة بالذكاء الاصطناعي في المنتج.
الاتصال: https://app.waafir.io/api/mcp/waafir، أو خادم المجال
https://app.waafir.io/api/mcp/waafir-translate؛ أسماء الأدوات متطابقة على كليهما — راجع
الإعداد. تحتاج translate_text و
translate_file_status إلى رمز PAT
بنطاق read (أو أعلى)؛ بينما تحتاج 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.
المتطلبات: خطة مدفوعة وتفعيل ميزات الذكاء الاصطناعي في مؤسستك (مفعّلة افتراضيًا؛ ويمكن لمسؤول المؤسسة إيقافها من الإعدادات ← الذكاء الاصطناعي والتكاملات). وتُرفض الاستدعاءات أيضًا بمجرد أن تبلغ مؤسستك حدّها اليومي لاستخدام الذكاء الاصطناعي، أو ما دامت 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. وهذا مقصود: فحلقة إعادة المحاولة التي تعيد
الإدراج في كل مرة ستستهلك موارد حوسبة ترجمة حقيقية في كل دورة.
المتطلبات: خطة مدفوعة، وتفعيل ميزات الذكاء الاصطناعي في مؤسستك (مفعّلة افتراضيًا؛ ويمكن لمسؤول المؤسسة إيقافها من الإعدادات ← الذكاء الاصطناعي والتكاملات)، و إذن بقراءة الملف وتنزيله.
ملف لا يزال قيد الفحص. إذا كان الملف رفعًا جديدًا أو إصدارًا جديدًا لم تُنهِ
Waafir فحصه بعد، تُجيب translate_file بـUNAVAILABLE مع
error.reason: "ACTIVATION_PENDING" والرسالة
This file is still being checked. Try again shortly. لا يُوضع شيء في قائمة
الانتظار؛ استدعِ الأداة مجددًا بعد انتظار قصير.
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 للتنزيل تُصدره هذه الأداة في سجل التدقيق الخاص بمؤسستك بوصفه تنزيلًا لملف، منسوبًا إلى الرمز وموسومًا بأنه صادر من عميل ذكاء اصطناعي — تمامًا كما يُسجَّل التنزيل عبر المنتج.