PTC

שליחה וקבלת תרגומים באמצעות ה-API

השתמשו ב-API זה כדי לשלוח תוכן לתרגום, לעקוב אחר התקדמותו ולקבל את התרגומים בכל שפות היעד.

ה-API מקבל תוכן במבנה JSON, תוך שמירה על המבנה והמפתחות המקוריים. הוא מתרגם רק ערכי טקסט, ומשאיר מספרים, ערכים בוליאניים, ערכי null וערכים אחרים שאינם טקסט ללא שינוי.

יצירת תרגומי תוכן

יוצר עבודת תרגום חדשה מנתונים במבנה JSON.

נקודת הקצה שומרת על ההיררכיה המקורית של המפתחות והמערכים בתוכן שלכם, ומתרגמת רק ערכי טקסט בעוד שמספרים, ערכים בוליאניים, ערכי null וערכים אחרים שאינם טקסט נותרים ללא שינוי.

זה שימושי במיוחד עבור:

  • ניהול תוכן – לוקליזציה של תוכן דינמי במבנה JSON
  • קובצי הגדרות – תרגום מחרוזות הפונות למשתמש בנתוני קונפיגורציה
  • תגובות API – תרגום גופי תגובה (payloads) מובנים
  • תיעוד – לוקליזציה של תכני עזרה או מדריכים היררכיים

למימוש מלא של תזרים עבודה זה ב-Rails, ראו תרגום תוכן דינמי ב-Rails באמצעות ה-API של PTC.

בקשת HTTP

POST https://app.ptc.wpml.org/api/v1/content_translation

פרמטרים

פרמטר סוג חובה תיאור
data object כן הנתונים במבנה JSON לתרגום. יכול לכלול אובייקטים מקוננים, מערכים וערכי מחרוזת.
name string לא שם קריא לעבודת התרגום. אם הושמט, שם ייווצר באופן אוטומטי.
callback_url string לא הכתובת (URL) שתקבל התראות webhook כאשר התרגום יושלם.
target_languages array[string] לא מערך של קודי ISO עבור שפות יעד. אם הושמט, ייווצרו תרגומים עבור כל השפות המוגדרות בפרויקט. ראו את ה- Available Target Languages API למידע נוסף.

דוגמה לגוף הבקשה

{
  "data": {
    "app": {
      "title": "My Application",
      "navigation": {
        "home": "Home",
        "about": "About Us",
        "contact": "Contact"
      },
      "buttons": {
        "save": "Save",
        "cancel": "Cancel",
        "submit": "Submit"
      },
      "messages": {
        "welcome": "Welcome to our platform",
        "error": "An error occurred"
      }
    },
    "version": "1.0.0",
    "settings": {
      "theme": "dark",
      "notifications": true
    }
  },
  "name": "App UI Translations",
  "callback_url": "https://your-app.com/webhooks/translation-complete",
  "target_languages": ["es", "fr", "de"]
}

תגובות

תגובת הצלחה

201 Createdapplication/json
{
  "id": 123,
  "name": "App UI Translations",
  "status": "queued",
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z"
}

סכימת תגובה

שדה סוג תיאור
id number המזהה הייחודי של עבודת תרגום התוכן.
name string שם העבודה (נוצר אוטומטית אם לא סופק).
status string הסטטוס הנוכחי של העבודה (queued, processing, completed).
created_at string חותמת זמן בפורמט ISO 8601 המציינת מתי נוצרה העבודה.
updated_at string חותמת זמן בפורמט ISO 8601 המציינת מתי העבודה עודכנה לאחרונה.

תגובות שגיאה

נתוני JSON לא תקינים
422 Unprocessable Entity
{
  "errors": {
    "data": ["Data must be a valid JSON object"]
  }
}
שפות יעד לא תקינות
422 Unprocessable Entity
{
  "errors": {
    "target_languages": ["Language codes [zh, xx] are not configured for this project"]
  }
}
Unauthorized (חוסר הרשאה)
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Forbidden (גישה אסורה)
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

עיבוד נתוני JSON

בעבודה עם נתונים במבנה JSON, ‏PTC מעבד את הנתונים באופן הבא:

  • שמירה על המבנה – ההיררכיה המקורית של המפתחות והקינון נותרת ללא שינוי
  • רק מחרוזות עוברות תרגום – מספרים, ערכים בוליאניים, מערכים וערכי null נשמרים כפי שהם
  • תרגום מבוסס נתיב – כל מחרוזת הניתנת לתרגום מזוהה על ידי נתיב ה-JSON שלה
  • תמיכה בקינון – עובד עם אובייקטים ומערכים המקוננים לעומק
  • טיפול בסוגי נתונים מעורבים – ערכים שאינם מחרוזות נשמרים ללא שינוי

דוגמה לטרנספורמציה של נתונים

קלט (Input):

{
  "user": {
    "name": "Welcome User",
    "settings": {
      "theme": "Choose Theme",
      "count": 5,
      "enabled": true
    }
  }
}

תוצאת העיבוד:

  • user.name: “Welcome User” ← מתורגם
  • user.settings.theme: “Choose Theme” ← מתורגם
  • user.settings.count: 5 ← נותר ללא שינוי
  • user.settings.enabled: true ← נותר ללא שינוי

תזרים עבודת התרגום

  1. אימות (Validation): מבנה ה-JSON ושפות היעד נבדקים
  2. הכנת קובץ מקור: ה-JSON מומר לפורמט מקור פנימי
  3. שימוש חוזר במחרוזות באמצעות זיכרון תרגומי: כל המחרוזות הניתנות לתרגום מחולצות ומאוחסנות בזיכרון התרגומי של הפרויקט שלכם, כך שניתן לעשות שימוש חוזר בתרגומים קודמים
  4. תור עבודות: עבודה נכנסת לתור עבור כל שפת יעד
  5. עיבוד: תרגום אוטומטי רץ על המחרוזות שחולצו
  6. Callback (אופציונלי): Webhook נשלח כאשר כל התרגומים הושלמו, במידה וסופק callback_url

Webhook Callback

כאשר מסופק callback_url, בקשת POST נשלחת עם סיום העבודה.

גוף בקשת ה-Callback:

{
  "id": 1,
  "status": "completed",
  "translations_url": "https://app.ptc.wpml.org/api/v1/content_translation/1"
}

סוגי נתונים נתמכים

סוג JSON התנהגות תרגום
string מתורגם לשפות היעד
number נשמר כפי שהוא
boolean נשמר כפי שהוא
null נשמר כפי שהוא
array מעובד באופן רקורסיבי
object מעובד באופן רקורסיבי

דוגמאות לבקשות

תרגום JSON בסיסי:

curl -X POST "https://app.ptc.wpml.org/api/v1/content_translation" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "welcome": "Welcome",
      "buttons": {
        "save": "Save",
        "cancel": "Cancel"
      }
    },
    "name": "UI Labels"
  }'

עם שפות יעד ספציפיות:

curl -X POST "https://app.ptc.wpml.org/api/v1/content_translation" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "title": "Product Catalog",
      "categories": {
        "electronics": "Electronics",
        "clothing": "Clothing"
      }
    },
    "target_languages": ["es", "fr"],
    "callback_url": "https://myapp.com/webhook"
  }'

דוגמאות קוד

curl -X POST "https://app.ptc.wpml.org/api/v1/content_translation" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data":{"app":{"title":"My Application","navigation":{"home":"Home","about":"About Us"}}},"name":"App Translations","target_languages":["es","fr","de"],"callback_url":"https://your-app.com/webhooks/complete"}'

# The response includes the job "id". Poll its status (status stays
# "in_progress" until done — it is not set on the create response):
curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/CONTENT_TRANSLATION_ID/status" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

קבלת תרגומי תוכן

שולף את התוכן המקורי ואת כל הגרסאות המתורגמות עבור עבודת תרגום תוכן ספציפית.

התגובה שומרת על מבנה הקלט שלכם: היא מחזירה אובייקט מקור (source) בתוספת אובייקט אחד לכל שפת יעד (המזוהה לפי קוד השפה, כגון es, fr, de).

בקשת HTTP

GET https://app.ptc.wpml.org/api/v1/content_translation/{id}

פרמטרי נתיב (Path Parameters)

פרמטר סוג חובה תיאור
id integer כן המזהה הייחודי של עבודת תרגום התוכן לשליפה.

תגובות

תגובת הצלחה

200 OKapplication/json
{
  "source": {
    "app": {
      "title": "My Application",
      "navigation": {
        "home": "Home",
        "about": "About",
        "contact": "Contact"
      },
      "buttons": {
        "save": "Save",
        "cancel": "Cancel"
      }
    }
  },
  "es": {
    "app": {
      "title": "Mi Aplicación",
      "navigation": {
        "home": "Inicio",
        "about": "Acerca de",
        "contact": "Contacto"
      },
      "buttons": {
        "save": "Guardar",
        "cancel": "Cancelar"
      }
    }
  },
  "fr": {
    "app": {
      "title": "Mon Application",
      "navigation": {
        "home": "Accueil",
        "about": "À propos",
        "contact": "Contact"
      },
      "buttons": {
        "save": "Enregistrer",
        "cancel": "Annuler"
      }
    }
  }
}

סכימת תגובה

שדה סוג תיאור
source object תוכן המקור המקורי באותו מבנה מקונן כפי שנשלח.
{language_code} object התוכן המתורגם עבור כל שפת יעד, המזוהה לפי קוד ה-ISO שלה (לדוגמה es, fr, de), באותו מבנה של המקור. למידע נוסף, ראו את ה- Available Target Languages API.

תגובות שגיאה

תרגום התוכן לא נמצא
404 Not Found
{
  "error": "Content translation not found"
}
Unauthorized (חוסר הרשאה)
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Forbidden (גישה אסורה)
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

דוגמאות לבקשות

בקשה בסיסית:

curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/123" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

דוגמאות קוד

curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/123" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

בדיקת סטטוס תרגום התוכן

שולף את הסטטוס הנוכחי של עבודת תרגום תוכן ספציפית.

התגובה משקפת את ההתקדמות הכוללת ומציינת האם התרגום נמצא בתור, בתהליך עיבוד, הושלם או נכשל.

בקשת HTTP

GET https://app.ptc.wpml.org/api/v1/content_translation/{id}/status

פרמטרי נתיב (Path Parameters)

פרמטר סוג חובה תיאור
id integer כן המזהה הייחודי של עבודת תרגום התוכן לבדיקה.

תגובות

תגובת הצלחה

200 OKapplication/json
{
  "status": "completed",
  "completeness": 100
}
סכימת תגובה
שדה סוג תיאור
status string סטטוס התרגום הנוכחי. ערכי סטטוס אפשריים כוללים: queued, in_progress, completed, failed, status_unknown.
completeness number אחוז המחרוזות שתורגמו (0–100). מחושב כ- (completed_translatable_strings / total_translatable_strings) × 100.
ערכי סטטוס
סטטוס תיאור
queued התרגום הוכנס לתור וממתין לעיבוד.
in_progress התרגום נמצא כעת בתהליך עיבוד.
completed התרגום הושלם בהצלחה.
failed התרגום נכשל עקב שגיאה.
status_unknown סטטוס התרגום אינו ידוע או שעדיין לא ניתן לקבוע אותו.

תגובות שגיאה

404 Not Found

סיבות אפשריות:

  • לא קיים תרגום תוכן עם המזהה שצוין
  • עבודת התרגום אינה שייכת לפרויקט המאומת

דוגמה

curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/123/status" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

תגובה:

{
  "status": "completed",
  "completeness": 100
}

תגובה בזמן שהעבודה עדיין רצה:

{
  "status": "in_progress",
  "completeness": 70
}
{
  "status": "completed",
  "completeness": 100
}