إدراج ترجمة خلفية غير متزامنة لجميع المستندات المنشورة من مخطط مكوّن واحد أو أكثر إلى مجموعة من اللغات المستهدفة. تُضاف النتائج أو تُحدّث في جدول translations عند اكتمال كل ترجمة.

نقطة النهاية: POST /translation المصادقة: Bearer JWT (WorkOS)

نص الطلب

{
  "websiteId": "<uuid>",
  "schemaNames": ["post", "hero"],
  "languages": ["fr", "es", "de"]
}

* يجب توفير schemaNames أو schemaName.

لا تُؤخذ في الاعتبار إلا المستندات المنشورة التي تحتوي على محتوى منشور غير فارغ.

الاستجابة

{
  "job_id": "<uuid>",
  "website_id": "<uuid>",
  "schema_name": null,
  "schema_names": ["post", "hero"],
  "languages": ["fr", "es", "de"],
  "status": "queued",
  "documents_processed": 12,
  "translations_scheduled": 30,
  "translations_skipped": 6,
  "translations_completed": 0,
  "translations_failed": 0,
  "reused": false,
  "created_at": "2026-07-15T18:00:00Z",
  "updated_at": "2026-07-15T18:00:00Z"
}

تُرجع ما يلي:

• 202 Accepted عند وضع الترجمات في قائمة الانتظار
• 200 OK عندما تكون كل ترجمة محدثة بالفعل
• المهمة النشطة الحالية عندما يكون هناك طلب مطابق قيد التشغيل بالفعل

حالات المهمة المحتملة هي:

• preparing
• queued
• running
• completed
• completed_with_errors
• failed

تخطي الترجمات الحالية

يخزّن كل زوج من المستند واللغة تجزئة SHA-256 للمحتوى المنشور للمستند المصدر.

يتم تخطي الترجمة عندما تتطابق تجزئة المصدر المخزنة مع المحتوى المنشور الحالي. يتيح ذلك استدعاء نقطة النهاية بشكل متكرر دون إعادة ترجمة المحتوى الذي لم يتغير.

إذا تغير المحتوى المنشور أثناء وجود مهمة مكافئة نشطة، ترفض الخدمة الطلب الجديد. أرسله مرة أخرى بعد انتهاء المهمة النشطة.

سلوك المعالجة

تُنفّذ الترجمة بشكل غير متزامن بعد الاستجابة الأولية.

• تتم معالجة العمل بدرجة تزامن محدودة.
• يُعاد تنفيذ الإخفاقات المؤقتة مع استخدام آلية تراجع تدريجي.
• تُحفظ النتائج الناجحة عند اكتمالها.
• تُسجّل إخفاقات الاستدلال أو الحفظ الفردية ضمن المهمة.
• تنتهي المهمة الناجحة جزئيًا بالحالة completed_with_errors.

مثال

curl -X POST '{TRANSLATION_API_URL}/translation' \
  -H 'Authorization: Bearer <workos-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "websiteId": "<uuid>",
    "schemaNames": ["post", "hero"],
    "languages": ["fr", "es"]
  }'

الأخطاء

• 400 Bad Request — المخططات أو اللغات مفقودة، أو اللغة غير مدعومة، أو أن الدفعة تتجاوز الحد المكوّن
• 401 Unauthorized — رمز الحامل مفقود أو غير صالح
• 409 Conflict — يوجد عمل مطابق نشط، لكن محتوى المصدر المنشور تغيّر
• 500 Internal Server Error — تعذّر إعداد المستندات المصدر أو فشلت عملية في قاعدة البيانات

الحصول على مهمة ترجمة

استرداد أحدث تقدم لمهمة ترجمة.

نقطة النهاية: GET /translation-jobs/{job_id} المصادقة: Bearer JWT (WorkOS)

الاستجابة

تستخدم الاستجابة كائن المهمة نفسه الذي يعيده POST /translation، مع تحديث الحالة وأعداد التقدم.

{
  "job_id": "<uuid>",
  "website_id": "<uuid>",
  "schema_name": null,
  "schema_names": ["post", "hero"],
  "languages": ["fr", "es"],
  "status": "running",
  "documents_processed": 12,
  "translations_scheduled": 24,
  "translations_skipped": 0,
  "translations_completed": 16,
  "translations_failed": 1,
  "reused": false,
  "created_at": "2026-07-15T18:00:00Z",
  "updated_at": "2026-07-15T18:01:30Z"
}

مثال

curl '{TRANSLATION_API_URL}/translation-jobs/<job-id>' \
  -H 'Authorization: Bearer <workos-jwt>'

الأخطاء

• 401 Unauthorized — رمز الحامل مفقود أو غير صالح
• 404 Not Found — المهمة غير موجودة أو لم تعد محفوظة

تُحفظ مهام الترجمة حاليًا في الذاكرة. تُفقد حالة المهمة عند إعادة تشغيل خدمة الترجمة، وتتطلب عمليات النشر متعددة النسخ توجيهًا ثابتًا.