مرجع API

مرجع كامل لكل نقطة نهاية، شكل الطلب والاستجابة، رمز الخطأ، وحدود المعدل.

الحدود والسلوك

بدل الرموز الشهري (الطبقة المجانية): قبل استدعاء النموذج، يقدر API الرموز تقريبًا كـ ceil(content_length / 4) × (number_of_targets + 1) وللطبقة free فقط، يرفض الطلب برمز 429 / token_limit_reached إذا كان التقدير سيتجاوز المنحة الشهرية المتبقية (الافتراضي 100000). الطبقات المدفوعة غير محجوبة بهذا الفحص المسبق؛ الاستخدام لا يزال مسجلاً.

حدود المعدل: عند تكوين Redis، تنطبق حدود دقيقة حسب الطبقة: مجانية 5، مبتدئ 30، نمو 60، مقياس 120، مؤسسة غير محدودة. عند الوصول للحد، تكون الاستجابة 429 مع error: "rate_limit_reached". إذا لم يتم تكوين Redis، يتم تخطي تحديد معدل الطلب.

قد تتضمن الاستجابات الناجحة المحدودة المعدل X-RateLimit-Limit، X-RateLimit-Remaining، X-RateLimit-Reset.

GET /health

لا حاجة للمصادقة.

استجابة 200

{
  "status": "ok",
  "timestamp": "2025-03-23T12:00:00.000Z"
}

GET /languages

لا حاجة للمصادقة.

يعيد القائمة الرسمية للغات المدعومة (الرمز، الاسم المعروض، علم RTL). هناك 43 مدخلاً — 36 لغة أساسية و7 متغيرات إقليمية. تستخدم المتغيرات الإقليمية رموز BCP-47 الفرعية للمنطقة (مثل fr-CA، pt-BR، es-MX). الرموز من هذه النقطة النهائية هي القيم الوحيدة المقبولة في targets على نقاط نهاية الترجمة.

استجابة 200

{
  "languages": [
    { "code": "en", "name": "الإنجليزية", "rtl": false },
    { "code": "ar", "name": "العربية", "rtl": true }
  ]
}

القائمة الحية متاحة أيضًا عبر GET /languages — انظر أدناه.

POST /translate

يتطلب Authorization: Bearer <api_key>.

يترجم سلسلة content واحدة إلى كل لغة مدرجة في targets. الاستجابة هي كائن JSON واحد مفاتيحه هي رموز اللغات المطلوبة وقيمه هي النصوص المترجمة.

جسم الطلب

استجابة 200

{
  "translations": {
    "es": "...",
    "fr": "..."
  },
  "usage": {
    "input_tokens": 120,
    "output_tokens": 340,
    "total_tokens": 460,
    "model": "standard",
    "detected_format": "markdown",
    "detection_confidence": 0.95
  }
}

detected_format و detection_confidence تظهر فقط عندما يتم حذف format وتم تشغيل الكشف التلقائي.

مثال (cURL)

curl -sS -X POST "https://api.usepolylingo.com/v1/translate" \
  -H "Authorization: Bearer $POLYLINGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "{\"title\":\"Hello\"}",
    "format": "json",
    "targets": ["fr", "de"]
  }'

مثال (Python 3)

pip install requests

import os, requests

url = "https://api.usepolylingo.com/v1/translate"
headers = {
    "Authorization": f"Bearer {os.environ['POLYLINGO_API_KEY']}",
    "Content-Type": "application/json",
}
r = requests.post(url, json={
    "content": "<p>Hello <strong>world</strong></p>",
    "format": "html",
    "targets": ["es"],
}, timeout=120)
r.raise_for_status()
print(r.json()["translations"]["es"])

POST /translate/batch

يتطلب Authorization: Bearer <api_key>.

يعالج كل عنصر تتابعيًا (نداء نموذج واحد لكل عنصر). إذا فشل أي عنصر، يعيد API 500 ولا يعيد نتائج جزئية لذلك الطلب.

جسم الطلب

استجابة 200

{
  "results": [
    { "id": "welcome", "translations": { "fr": "...", "de": "..." } },
    { "id": "goodbye", "translations": { "fr": "...", "de": "..." } }
  ],
  "usage": {
    "total_tokens": 900,
    "input_tokens": 400,
    "output_tokens": 500,
    "model": "standard"
  }
}

مثال

curl -sS -X POST "https://api.usepolylingo.com/v1/translate/batch" \
  -H "Authorization: Bearer $POLYLINGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "id": "a", "content": "Hello", "format": "plain" },
      { "id": "b", "content": "## Title", "format": "markdown" }
    ],
    "targets": ["es", "it"]
  }'

POST /jobs

يتطلب Authorization: Bearer <api_key>.

يضع وظيفة ترجمة في قائمة الانتظار ويعيد فورًا مع job_id. الترجمة تعمل في الخلفية — لا خطر انتهاء مهلة HTTP بغض النظر عن حجم المحتوى. استعلم GET /jobs/:id عن النتيجة.

استخدم هذه النقطة النهائية بدلاً من POST /translate عند ترجمة مستندات كبيرة (Markdown طويل، العديد من لغات الهدف) حيث قد تتجاوز مدة الطلب مهلة عميل HTTP أو البروكسي الخاص بك.

جسم الطلب

استجابة 202

{
  "job_id": "a1b2c3d4-...",
  "status": "pending",
  "created_at": "2025-03-23T12:00:00.000Z"
}

GET /jobs/:id

يتطلب Authorization: Bearer <api_key>.

يستعلم عن حالة وظيفة تم إرسالها عبر POST /jobs. استعلم كل 5–10 ثوانٍ. الوظائف مملوكة للمستخدم المرسل — المستخدمون الآخرون يتلقون 404.

استجابة (قيد الانتظار / المعالجة)

{
  "job_id": "a1b2c3d4-...",
  "status": "pending",
  "created_at": "2025-03-23T12:00:00.000Z",
  "updated_at": "2025-03-23T12:00:00.000Z",
  "completed_at": null,
  "queue_position": 3
}

status هو pending (انتظار عامل) أو processing (العامل استلمها). queue_position (مبني على 1) هو عدد الوظائف المعلقة أو المعالجة التي تم إنشاؤها قبل هذه الوظيفة — استخدمه لواجهة المستخدم الخاصة بالتقدم. يتم حذفه عند فشل استعلام العد.

استجابة (مكتملة)

{
  "job_id": "a1b2c3d4-...",
  "status": "completed",
  "created_at": "2025-03-23T12:00:00.000Z",
  "updated_at": "2025-03-23T12:00:02.000Z",
  "completed_at": "2025-03-23T12:00:02.000Z",
  "translations": {
    "es": "...",
    "fr": "..."
  },
  "usage": {
    "input_tokens": 120,
    "output_tokens": 340,
    "total_tokens": 460,
    "model": "standard"
  }
}

استجابة (فشل)

{
  "job_id": "a1b2c3d4-...",
  "status": "failed",
  "error": "Model returned invalid JSON"
}

مثال (JavaScript)

const API = 'https://api.usepolylingo.com/v1'
const headers = {
  'Authorization': `Bearer ${process.env.POLYLINGO_API_KEY}`,
  'Content-Type': 'application/json',
}

// 1. إرسال
const submit = await fetch(`${API}/jobs`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ content: longMarkdown, format: 'markdown', targets: ['de', 'fr'] }),
})
const { job_id } = await submit.json()

// 2. استعلام
while (true) {
  await new Promise(r => setTimeout(r, 10_000))
  const poll = await fetch(`${API}/jobs/${job_id}`, { headers })
  const job = await poll.json()
  if (job.status === 'completed') { console.log(job.translations); break }
  if (job.status === 'failed')    { throw new Error(job.error) }
  // اختياري: عرض التقدم (queue_position مبني على 1، يحذف عند عدم وجود قائمة انتظار)
  if (job.queue_position != null) console.log(`موقع في القائمة: ${job.queue_position}`)
}

GET /usage

يتطلب Authorization: Bearer <api_key> (بحث مفتاح قياسي — ليس مسار تجاوز داخلي فقط).

يعيد استخدام الرموز للشهر الميلادي الحالي للمستخدم المصادق عليه.

استجابة 200

{
  "period_start": "2025-03-01T00:00:00.000Z",
  "period_end": "2025-03-31T23:59:59.000Z",
  "tokens_used": 12000,
  "tokens_included": 100000,
  "tokens_remaining": 88000,
  "overage_tokens": 0,
  "tier": "free"
}

tokens_included و tokens_remaining هما null للطبقة enterprise (منحة غير محدودة في التقارير).

تنسيقات المحتوى

القيم المدعومة لـ format: plain، markdown، json، html.

RTL والاتجاه في تطبيقك

لـ plain و markdown، يعيد API النص المترجم فقط — لا يضيف dir="rtl" أو عناصر التغليف. اضبط اتجاه النص في واجهة المستخدم الخاصة بك (CSS direction، سمة dir لعنصر أب، أو تخطيط i18n في إطار العمل) عند عرض العربية أو العبرية أو الفارسية.

لتنسيق html، قد يتضمن الوسم المترجم dir="rtl" حيثما كان مناسبًا لأهداف RTL.

استجابات الأخطاء

الأخطاء تكون بصيغة JSON عندما يكون ذلك ممكنًا:

{
  "error": "invalid_request",
  "message": "تفصيل قابل للقراءة من قبل الإنسان"
}

قد يعيد GET /usage رمز 500 مع رسالة عامة إذا فشل استعلام Supabase.