PTC

בקשה ואחזור של תרגומים דרך ה־API

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

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

Create Content Translations

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

ה־endpoint שומר על ההיררכיה המקורית של המפתחות והמערכים בתוכן שלכם, מתרגם רק ערכי טקסט ומשאיר מספרים, ערכים בוליאניים, ערכי 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 עבור שפות יעד. אם יושמט, ייווצרו תרגומים לכל השפות שהוגדרו בפרויקט. למידע נוסף, ראו את 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"]
  }
}
לא מורשה
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
גישה נדחתה
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

עיבוד נתוני JSON

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

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

דוגמה להתמרת נתונים

קלט:

{
  "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. אימות: מבנה ה־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 (the create response
# carries a "status" field as well, but it is usually null until the run
# starts, and stays "in_progress" until done):
curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/CONTENT_TRANSLATION_ID/status" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Get Content Translations

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

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

בקשת HTTP

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

פרמטרי נתיב

פרמטר סוג חובה תיאור
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), באותו מבנה כמו המקור. למידע נוסף, ראו את API שפות יעד זמינות.

תגובות שגיאה

תרגום התוכן לא נמצא
404 Not Found
{
  "error": "Content translation not found"
}
לא מורשה
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
גישה נדחתה
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"

Get the Content Translation Status

מאחזר את הסטטוס הנוכחי של משימת תרגום ספציפית.

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

בקשת HTTP

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

פרמטרי נתיב

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

תגובות

תגובת הצלחה

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

תגובות שגיאה

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
}