توثيق API لتكامل ترجمات TranslatePress (TP Sync API)

Этот API предоставляет два эндпоинта для работы со строками переводов в плагине TranslatePress. Базовый язык — английский (en_us). تتطلب جميع الطلبات تفويضًا عبر رمز Bearer (يتم الحصول عليه في لوحة إدارة WordPress ضمن قائمة "TP Sync").

عنوان URL الأساسي: https://your-site.com/wp-json/tp-sync/v1/

1. الحصول على السلاسل للترجمة (GET /keys)

تُرجع نقطة النهاية هذه قائمة بالسلاسل من قاموس TranslatePress للغة المحددة. تتضمن كل سلسلة ID (بالتنسيق, القاموس:{id}), النص الأصلي باللغة الإنجليزية, الترجمة الحالية, الحالة وبيانات تعريف ترقيم الصفحات. الفرز حسب ID DESC (الأحدث في الأعلى). التواريخ, created_at و updated_at دائمًا null (لا يتم طلبها في SQL).

معلمات الطلب

المعلمة،	النوع	مطلوب	الوصف	القيمة الافتراضية
lang	سلسلة نصية	نعم	Код языка (например, de للألمانية, fr للفرنسية). يتم تطبيع الرموز القصيرة (de → de_de).	—
صفحة	عدد صحيح	لا	رقم الصفحة للتصفح.	1
حد	عدد صحيح	لا	عدد الصفوف في الصفحة (الحد الأدنى 1، الحد الأقصى 500).	100
updated_since	سلسلة نصية	لا	Фильтр по дате обновления (ISO8601, например, 2025-10-01T00:00:00Z). يُرجع فقط الصفوف التي تم تحديثها بعد هذا التاريخ.	—

العناوين

• Authorization: Bearer {токен} (مطلوب)

مثال طلب (cURL)

curl -X GET "https://your-site.com/wp-json/tp-sync/v1/keys?lang=de&page=1&limit=50&updated_since=2025-10-01T00:00:00Z" \
  -H "Authorization: Bearer your-api-token-here"

مثال على الرد (JSON)

{
  "keys": [
    {
      "key_id": "dictionary:123",
      "original": "Hello World",
      "translated": "Hallo Welt",
      "status": 2,
      "created_at": null,
      "updated_at": null
    },
    {
      "key_id": "dictionary:124",
      "original": "Welcome",
      "translated": "",
      "status": 0,
      "created_at": null,
      "updated_at": null
    }
  ],
  "meta": {
    "total_count": 150,
    "page": 1,
    "limit": 50,
    "page_count": 3,
    "next_page": "https://your-site.com/wp-json/tp-sync/v1/keys?lang=de&page=2&limit=50&updated_since=2025-10-01T00:00:00Z"
  }
}

وصف الحقول في الاستجابة

حقل	النوع	الوصف
key_id	سلسلة نصية	المعرّف الفريد للصف: القاموس:{id} id — رقم السجل في الجدول wp_trp_dictionary_en_us_{lang}).
الأصلي	سلسلة نصية	النص الأصلي باللغة الإنجليزية.
مترجم	سلسلة نصية	الترجمة الحالية للغة المحددة (قد تكون فارغة).
الحالة	عدد صحيح	الحالة: 0 — غير مترجم, 1 — قيد التنفيذ, 2 — مترجم.
created_at	سلسلة نصية	تاريخ الإنشاء (ISO8601, null — لا يُطلب).
updated_at	سلسلة نصية	Дата последнего обновления (ISO8601, null — لا يُطلب).

البيانات الوصفية (meta)

• total_count: إجمالي عدد الصفوف (مع مراعاة عوامل التصفية).
• صفحة: الصفحة الحالية.
• حد: حد لكل صفحة.
• page_count=: إجمالي عدد الصفحات.
• الصفحة_التالية: URL следующей страницы (null, إذا كانت الأخيرة).

أخطاء

• 401: ترويسة Authorization مفقودة أو غير صالحة.
• 403: رمز مميز غير صالح.
• 404: لم يتم العثور على اللغة في TranslatePress (الجدول غير موجود).

2. تحديث الترجمات (POST /translations)

تقوم نقطة النهاية هذه بتحديث الترجمات لعدة سلاسل في كل مرة (دفعة). يتم تمرير مصفوفة من الكائنات تحتوي على ID السلسلة واللغة والترجمة الجديدة. تقوم بتحديث الحالة إلى "مترجم" (2) والحقل, updated_at.

نص الطلب (JSON)

مصفوفة الترجمات مع الكائنات:

{
  "translations": [
    {
      "key_id": "dictionary:123",
      "language_iso": "de",
      "translation": "Hallo Welt"
    },
    {
      "key_id": "dictionary:124",
      "language_iso": "de",
      "translation": "Willkommen"
    }
  ]
}

الإعدادات

حقل في الكائن,	النوع	مطلوب	الوصف
key_id	سلسلة نصية	نعم	معرّف الصف: القاموس:{id} (من GET /keys).
language_iso	سلسلة نصية	نعم	رمز اللغة (de → de_de, تتم تسويته تلقائيًا).
ترجمة	سلسلة نصية	نعم	Новый текст перевода (сохраняется как есть).

العناوين

• Authorization: Bearer {токен} (مطلوب)
• Content-Type: application/json (مطلوب)

مثال طلب (cURL)

curl -X POST "https://your-site.com/wp-json/tp-sync/v1/translations" \
  -H "Authorization: Bearer your-api-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "translations": [
      {
        "key_id": "dictionary:123",
        "language_iso": "de",
        "translation": "Hallo Welt"
      }
    ]
  }'

مثال على الرد (JSON)

{
  "translations": [
    {
      "key_id": "dictionary:123",
      "language_iso": "de",
      "translation": "Hallo Welt",
      "modified_at": "2025-10-15T12:00:00Z"
    }
  ],
  "errors": [
    {
      "index": 1,
      "key_id": "dictionary:999",
      "error": "Key not found in database"
    }
  ]
}

وصف الحقول في الاستجابة

• الترجمات: مصفوفة الترجمات التي تم تحديثها بنجاح (تعيد بيانات الإدخال + modified_at بتنسيق ISO8601).
• أخطاء (اختياري, في حال وجود حالات فشل): مصفوفة الأخطاء.
  • فهرس: فهرس العنصر في المصفوفة المصدر.
  • key_id: ID الصف الذي به مشكلة (إن وجد).
  • خطأ: نص الخطأ (أمثلة: "الحقول المطلوبة مفقودة", "تنسيق key_id غير صالح. المتوقع: dictionary:{id}", "لم يتم العثور على اللغة", "لم يتم العثور على المفتاح في قاعدة البيانات", "فشل تحديث قاعدة البيانات").

أخطاء

• 400: Неверные данные (пустой/не-массив الترجمات, عدم وجود الحقول).
• 401/403: مشكلات في التفويض.
• 404: لم يتم العثور على اللغة أو المفتاح (الجدول/السجل غير موجود).

اللغات المدعومة

تتم تسوية الأكواد القصيرة تلقائيًا (استنادًا إلى التعيين في الكود). بالنسبة للمجهولة:, {code}_{code} (مثلاً, pl → pl_pl).

• en → en_us
• ar → ar
• id → id_id
• ko → ko_kr
• tr → tr_tr
• vi → vi
• ru → ru_ru
• fr → fr_fr
• de → de_de
• it → it_it
• ja → ja
• pt → pt_pt
• zh → zh_cn
• es → es_es

الحصول على الرمز المميز

• في لوحة إدارة WordPress: القائمة, مزامنة TP → زر "إنشاء رمز جديد" (رمز مكوّن من 32 حرفًا, يتم إنشاؤه تلقائيًا عند التشغيل الأول).
• يتم تخزين الرمز المميز في الخيار, tp_sync_api_token.