PTC

העלאה וניהול של קובצי מקור דרך ה־API

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

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

כיצד ה־API של PTC מזהה ומארגן קובצי מקור

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

תגיות קובץ

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

  • בקרת גרסאות: v1.0, beta, production
  • ענפי פיצ'רים: user-auth, dashboard-redesign
  • הקשר האפליקציה: mobile-app, admin-panel, marketing
  • בעלות צוות: frontend-team, content-team
  • מצב תהליך העבודה: approved, pending-review, priority-high

שמות של תגיות קובץ הם אופציונליים ברוב פעולות ה־API. עם זאת, לכל קובץ מקור יש תמיד לפחות תגית אחת. תגית קובץ המהווה ברירת מחדל נוצרת ומוקצית אוטומטית בעת הקמת פרויקט. התנהגות ברירת מחדל זו שומרת על פרויקטים מאורגנים גם בהגדרות פשוטות, ובמקביל מאפשרת לכם לבנות מבני תיוג מתקדמים יותר בעת הצורך.

שם תגית קובץ + נתיב קובץ

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

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

פרמטרי שאילתה

בעת אחזור קובץ מסוים, ה־endpoints הרלוונטיים יכולים לקבל פרמטרי שאילתה כגון:

  • file_tag_name – התגית המשויכת לקובץ
  • file_path – הנתיב לקובץ

פרמטרים אלו מאפשרים לכם לאתר ולאחזר במדויק את הקבצים הנכונים מתוך הפרויקט שלכם.


רשימת כל קובצי המקור בפרויקט

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

בקשת HTTP

GET https://app.ptc.wpml.org/api/v1/source_files

פרמטרים

פרמטר סוג חובה ברירת מחדל תיאור
page integer לא 1 מספר העמוד לעימוד. חייב להיות גדול מ־0.
per_page integer לא 50 מספר הפריטים בעמוד. חייב להיות גדול מ־0.
order_by string לא created_at השדה שלפיו יתבצע המיון. ערכים מורשים: id, created_at, updated_at.
sort string לא desc כיוון המיון. ערכים מורשים: asc, desc.
file_path string לא – מסנן לפי נתיב קובץ מדויק.
upload_origin string לא – מסנן לפי אופן העלאת הקובץ. ערכים מורשים כוללים: git, manual, api.

תגובות

תגובת הצלחה

200 OKapplication/json
{
  "source_files": [
    {
      "id": 123,
      "file_path": "locales/en.po",
      "translation_path": "locales/{{lang}}.po",
      "additional_translation_files": ["locales/{{lang}}.mo"],
      "status": "completed",
      "upload_origin": "git",
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T14:20:00.000Z",
      "file_tag": {
        "id": 456,
        "name": "frontend"
      },
      "download_url": "https://app.ptc.wpml.org/api/v1/source_files/download_translations?file_path=locales/en.po&file_tag_name=frontend"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 150,
    "total_pages": 3,
    "has_next_page": true,
    "has_previous_page": false
  }
}
סכמת התגובה

אובייקט קובץ מקור:

שדה סוג תיאור
id integer המזהה הייחודי של קובץ המקור.
file_path string הנתיב לקובץ המקור בתוך הפרויקט.
translation_path string התבנית עבור המיקום שבו ישמרו הקבצים המתורגמים.
additional_translation_files array[string] הנתיבים עבור קבצי פלט נוספים כלשהם.
status string סטטוס העיבוד הנוכחי של קובץ המקור.
upload_origin string אופן העלאת הקובץ (git, manual, api).
created_at string חותמת זמן בפורמט ISO 8601 המציינת מתי נוצר קובץ המקור לראשונה.
updated_at string חותמת זמן בפורמט ISO 8601 המציינת מתי עודכן קובץ המקור לאחרונה.
file_tag object מידע על תגית הקובץ.
file_tag.id integer מזהה תגית הקובץ.
file_tag.name string שם תגית הקובץ.
download_url string ה־URL להורדת תרגומים עבור קובץ מקור זה.

אובייקט עימוד:

שדה סוג תיאור
page integer מספר העמוד הנוכחי.
per_page integer מספר הפריטים בעמוד.
total integer סך כל קובצי המקור.
total_pages integer סך כל העמודים.
has_next_page boolean האם קיים עמוד הבא.
has_previous_page boolean האם קיים עמוד קודם.

תגובות שגיאה

לא מורשה
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
גישה נדחתה
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}
פרמטרים לא תקינים
422 Unprocessable Entity
{
  "error": "Invalid parameters provided."
}

בקשות לדוגמה

בקשה בסיסית:

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

בקשה מסוננת:

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files?file_tag_name=frontend&page=1&per_page=25&order_by=updated_at&sort=desc" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

דוגמאות קוד

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files?file_tag_name=frontend&page=1&per_page=25" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

אחזור מחרוזות תרגום

מאחזר את כל המחרוזות הניתנות לתרגום מתוך קובץ מקור מסוים, יחד עם התרגומים הקיימים שלהן בכל שפות היעד.

ה־endpoint הזה שימושי לאחזור תוכן שדורש תרגום או שכבר תורגם. קובץ המקור מזוהה באמצעות file_path ו־file_tag_name.

בקשת HTTP

GET https://app.ptc.wpml.org/api/v1/source_files/translation_strings

פרמטרים

פרמטר סוג חובה ברירת מחדל תיאור
file_path string כן – הנתיב לקובץ המקור בתוך הפרויקט.
file_tag_name string לא – שם תגית הקובץ. אם לא צוין, נעשה שימוש בתגית ברירת המחדל של הפרויקט.
page integer לא 1 מספר העמוד לעימוד (משמש בתור cursor). חייב להיות גדול מ־0.
q string לא – שאילתת החיפוש לסינון מחרוזות תרגום לפי טקסט המקור שלהן.

תגובות

תגובת הצלחה

200 OKapplication/json
{
  "total_strings_count": 1250,
  "translation_strings": [
    {
      "source": "Welcome to our application",
      "translations": {
        "es": "Bienvenido a nuestra aplicación",
        "fr": "Bienvenue dans notre application",
        "de": "Willkommen in unserer Anwendung"
      }
    },
    {
      "source": "Login",
      "translations": {
        "es": "Iniciar sesión",
        "fr": "Connexion",
        "de": "Anmelden"
      }
    }
  ],
  "cursor": 1
}
סכימת תגובה
שדה סוג תיאור
total_strings_count integer המספר הכולל של מחרוזות לתרגום בקובץ המקור.
translation_strings array[object] מערך של אובייקטים של מחרוזות תרגום (ממוספר לדפים, מקסימום 500 לדף).
translation_strings[].source string טקסט המקור המיועד לתרגום.
translation_strings[].translations object hash של תרגומים שבו המפתחות הם קודי ISO של שפות והערכים הם הטקסט המתורגם.
cursor integer ה־cursor של העמוד הנוכחי המשמש לחלוקה לדפים.

תגובות שגיאה

קובץ המקור לא נמצא
404 Not Found
{
  "error": "Source file not found"
}
לא מורשה
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
גישה נדחתה
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}
פרמטרים לא תקינים
422 Unprocessable Entity
{
  "error": "Invalid parameters provided."
}

בקשות לדוגמה

בקשה בסיסית:

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/translation_strings?file_path=locales/en.po" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

בקשה עם תגית קובץ:

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/translation_strings?file_path=locales/en.po&file_tag_name=frontend" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

בקשה עם חלוקה לדפים וחיפוש:

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/translation_strings?file_path=locales/en.po&file_tag_name=frontend&page=2&q=welcome" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

דוגמאות קוד

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/translation_strings?file_path=locales/en.po&file_tag_name=frontend&page=1&q=login" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

יצירת קובץ המקור

רושם קובץ מקור חדש בפרויקט שלכם כדי שיהיה מוכן לתרגום.

ה־endpoint הזה יוצר את ערך הקובץ ומגדיר את תצורת התרגום שלו, אך אינו מצרף את תוכן הקובץ עצמו.

לאחר יצירת הקובץ, תצטרכו להשתמש ב־endpoint עיבוד קובץ המקור כדי להעלות את התוכן ולהתחיל את תהליך התרגום.

בקשת HTTP

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

פרמטרים

פרמטר סוג חובה תיאור
file_path string כן הנתיב שבו קובץ המקור יישמר בפרויקט. חייב להיות בעל סיומת נתמכת.
output_file_path string כן תבנית נתיב הפלט עבור הקבצים המתורגמים. השתמשו ב־{{lang}} כמציין מיקום עבור קוד השפה.
file_tag_name string לא השם של תגית הקובץ שתחתיה יירשם קובץ המקור. אם לא סופק, ייעשה שימוש בתגית הקובץ המוגדרת כברירת מחדל בפרויקט.
translations array[object] לא קובצי תרגומים קיימים להעלאה לצד קובץ המקור. קבצים אלו יישמרו כפי שסופקו, והמחרוזות שלהם לא יתורגמו מחדש על ידי PTC. שימו לב כי אספקת תרגומים קיימים אינה מומלצת, מכיוון ש־PTC מפיקה תוצאות טובות יותר כאשר היא יכולה להשתמש בהקשר המלא של הפרויקט שלכם ולבצע תרגום מאפס.
translations[].target_language_iso string כן קוד ה־ISO של שפת היעד עבור תרגום זה. תוכלו למצוא את הרשימה המלאה של השפות הנתמכות וקודי ה־ISO שלהן ב־endpoint List All Target Languages.
translations[].file file כן קובץ התרגום להעלאה.
additional_translation_files array[object] לא תצורות של קבצי פלט נוספים עבור פורמטים מסוימים. כדי לראות אילו פורמטים תומכים בקבצי פלט נוספים, עיינו ב־endpoint List Supported File Formats. עבור פורמטים שאינם נתמכים, המערכת תתעלם משדה זה.
additional_translation_files[].type string כן ראו פורמטים נתמכים של קבצים לפרטים נוספים.
additional_translation_files[].path string כן תבנית הנתיב עבור הקובץ.

תגובות

תגובת הצלחה

201 Createdapplication/json
{
  "source_file": {
    "id": 123,
    "file_path": "src/locales/en.json",
    "created_at": "2024-01-15T10:30:00.000Z",
    "file_tag": {
      "id": 456,
      "name": "frontend"
    }
  }
}
סכימת תגובה
שדה סוג תיאור
source_file.id integer המזהה הייחודי עבור קובץ המקור שנוצר.
source_file.file_path string הנתיב של קובץ המקור בתוך הפרויקט.
source_file.created_at string חותמת זמן בתקן ISO 8601 המציינת מתי קובץ המקור נוצר.
source_file.file_tag.id integer המזהה של תגית הקובץ.
source_file.file_tag.name string השם של תגית הקובץ.

תגובות שגיאה

האימות נכשל
422 Unprocessable Entity
{
  "success": false,
  "error": "Source file creation failed"
}
לא מורשה
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
פעולה אסורה
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

בקשות לדוגמה

יצירה בסיסית של קובץ מקור:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file_path=src/locales/en.json" \
  -F "output_file_path=src/locales/{{lang}}.json" \
  -F "file_tag_name=frontend"

Create אינו מקבל את callback_url. רישום קובץ מקור אינו מתחיל שום תרגום, ולכן אין ל־callback מה להודיע — במקום זאת, העבירו אותו אל עיבוד קובץ המקור או אל העלאת קובצי מקור באצווה, שהן הקריאות שמתחילות את העבודה.

בקשה עם תרגומים קיימים:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file_path=src/messages.json" \
  -F "output_file_path=locales/{{lang}}/messages.json" \
  -F "translations[0][target_language_iso]=es" \
  -F "translations[0][file]=@spanish_translations.json" \
  -F "translations[1][target_language_iso]=fr" \
  -F "translations[1][file]=@french_translations.json"

בקשה עם קבצי פלט נוספים:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file_path=src/messages.po" \
  -F "output_file_path=locales/{{lang}}/messages.po" \
  -F "additional_translation_files[][type]=mo" \
  -F "additional_translation_files[][path]=locales/{{lang}}/messages.mo" \
  -F "additional_translation_files[][type]=json" \
  -F "additional_translation_files[][path]=locales/{{lang}}/messages.json"

דוגמאות קוד

  • JavaScript (FormData)
  • Python (requests)
  • PHP (cURL)
  • Node.js (axios)
  • גוף בקשת ה־callback
curl -X POST "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file_path=src/locales/en.json" \
  -F "output_file_path=src/locales/{{lang}}.json"
{
  "source_file_id": 123,
  "status": "completed",
  "file_tag_name": "frontend",
  "download_url": "https://app.ptc.wpml.org/api/v1/source_files/download_translations?file_path=src/locales/en.json&file_tag_name=frontend",
  "file_path": "src/locales/en.json"
}

Process the Source File

מעלה תוכן אל קובץ מקור קיים ומתחיל את תהליך התרגום.

endpoint זה מחליף את התוכן הנוכחי של הקובץ, מעדכן את המחרוזות לתרגום השמורות, ומתחיל תרגום אוטומטי.

כדי להשתמש ב־endpoint זה, קובץ המקור חייב להיות כבר קיים בפרויקט. אם עדיין לא יצרתם אותו, ראו יצירת קובץ המקור.

בקשת HTTP

PUT https://app.ptc.wpml.org/api/v1/source_files/process

פרמטרים

פרמטר סוג חובה תיאור
file file כן קובץ המקור להעלאה. תוכן הקובץ עובר אימות כדי לוודא שהוא תואם לסיומת הקובץ המוצהרת שלו. לדוגמה, אם סיומת הקובץ היא .json, התוכן המועלה חייב להיות JSON תקין.
file_path string כן הנתיב אל קובץ המקור הקיים בפרויקט שיש לעדכן.
file_tag_name string לא שם תגית הקובץ המשויכת לקובץ המקור. אם לא סופק, נעשה שימוש בתגית הקובץ המוגדרת כברירת מחדל בפרויקט.
callback_url string לא כתובת ה־URL שמקבלת התראות webhook כאשר עיבוד הקובץ מסתיים.

תגובות

תגובת הצלחה

200 OKapplication/json
{
  "source_file": {
    "id": 123,
    "file_path": "src/locales/en.json",
    "created_at": "2024-01-15T10:30:00.000Z",
    "file_tag": {
      "id": 456,
      "name": "frontend"
    }
  }
}
סכמת התגובה
שדה סוג תיאור
source_file.id integer המזהה הייחודי עבור קובץ המקור שעובד.
source_file.file_path string הנתיב של קובץ המקור בתוך הפרויקט.
source_file.created_at string חותמת זמן בתקן ISO 8601 המציינת מתי קובץ המקור נוצר במקור.
source_file.file_tag.id integer מזהה תגית הקובץ.
source_file.file_tag.name string שם תגית הקובץ.

תגובות שגיאה

פורמט קובץ לא נתמך או לא תקין

Process מחליף את תוכן הקובץ בתוכן שאתם מעלים, ולכן אין חיפוש שיכול להיכשל — ל־endpoint זה אין מצב של לא נמצא (not-found). הדחייה היחידה שהוא כן מחזיר היא בדיקת התוכן של הקובץ המועלה.

422 Unprocessable Entity
{
  "success": false,
  "message": "Unprocessable Entity",
  "code": 422,
  "errors": [9001]
}

errors הוא מערך של קודים מספריים, ולא אובייקט מבוסס מפתחות. 9001 פירושו שהתוכן לא פוענח בהתאם לפורמט שסיומת הקובץ שלו מצהירה. חלק מהדחיות מוסיפות לצידו אובייקט additional_info עם הפרטים הספציפיים.

לא מורשה (Unauthorized)
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
פעולה אסורה (Forbidden)
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

תהליך עבודה

  1. דרישת קדם: קובץ המקור חייב להיווצר מראש דרך יצירת קובץ המקור.
  2. העלאת קובץ: תוכן חדש מועלה ומחליף את תוכן הקובץ הקיים.
  3. עיבוד: המחרוזות החדשות לתרגום מחולצות ומתורגמות אוטומטית.
  4. Callback: התראת webhook אופציונלית נשלחת כאשר העיבוד מסתיים.

Webhook Callback

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

גוף הבקשה של ה־callback:

{
  "source_file_id": 123,
  "status": "completed",
  "file_tag_name": "frontend",
  "download_url": "https://app.ptc.wpml.org/api/v1/source_files/download_translations?file_path=src/locales/en.json&file_tag_name=frontend",
  "file_path": "src/locales/en.json"
}

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

עיבוד קובץ בסיסי:

curl -X PUT "https://app.ptc.wpml.org/api/v1/source_files/process" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@updated_translations.json" \
  -F "file_path=src/locales/en.json" \
  -F "file_tag_name=frontend"

בקשה עם callback URL:

curl -X PUT "https://app.ptc.wpml.org/api/v1/source_files/process" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@messages.po" \
  -F "file_path=locales/messages.po" \
  -F "callback_url=https://your-app.com/webhooks/translation-complete"

דוגמאות קוד

curl -X PUT "https://app.ptc.wpml.org/api/v1/source_files/process" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@updated_translations.json" \
  -F "file_path=src/locales/en.json" \
  -F "file_tag_name=frontend" \
  -F "callback_url=https://your-app.com/webhooks/complete"

פורמטים נתמכים של קבצים

ה־endpoint תומך במגוון פורמטים של קבצים לתרגום, כולל קובצי JSON, PO/POT, XLIFF ו־Properties, בין היתר. אימות של פורמט הקובץ מתבצע במהלך ההעלאה כדי להבטיח תאימות.

השתמשו ב־endpoint List Supported File Formats כדי לקבל את הרשימה המלאה של הפורמטים הנתמכים.


קבלת סטטוס התרגום

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

אפשרות זו שימושית עבור:

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

בקשת HTTP

GET https://app.ptc.wpml.org/api/v1/source_files/translation_status

פרמטרים

פרמטר סוג חובה תיאור
file_path string כן הנתיב לקובץ המקור בתוך הפרויקט.
file_tag_name string לא שם תגית הקובץ. אם לא מסופק, נעשה שימוש בתגית הקובץ המוגדרת כברירת מחדל בפרויקט.

תגובות

תגובת הצלחה

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

ערכי סטטוס

השדה status יכול להכיל את הערכים הבאים:

סטטוס תיאור
pending קובץ המקור ממתין לעיבוד.
processing התרגום נמצא כעת בתהליך.
completed כל התרגומים הושלמו.
failed תהליך התרגום נתקל בשגיאות.

תגובות שגיאה

קובץ מקור לא נמצא (Source File Not Found)
404 Not Found
{
  "error": "Source file not found"
}
לא מורשה (Unauthorized)
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
פעולה אסורה (Forbidden)
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}
פרמטרים לא חוקיים (Invalid Parameters)
422 Unprocessable Entity
{
  "error": "Invalid parameters provided."
}

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

בקשה בסיסית:

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/translation_status?file_path=locales/en.po" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

בקשה עם תגית קובץ:

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/translation_status?file_path=locales/en.po&file_tag_name=frontend" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

דוגמאות קוד

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/translation_status?file_path=locales/en.po&file_tag_name=frontend" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

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

מוריד את כל הקבצים המתורגמים עבור קובץ מקור ספציפי כקובץ ZIP.

ה־endpoint הזה יוצר ומחזיר קובץ דחוס (archive) המכיל את כל קובצי התרגום בשפות היעד עבור קובץ המקור שצוין.

אם אין תרגומים זמינים עבור הקובץ, הבקשה תחזיר שגיאת 404 Not Found.

בקשת HTTP

GET https://app.ptc.wpml.org/api/v1/source_files/download_translations

פרמטרים

פרמטר סוג חובה תיאור
file_path string כן הנתיב לקובץ המקור בתוך הפרויקט.
file_tag_name string לא שם תגית הקובץ. אם לא מסופק, נעשה שימוש בתגית הקובץ המוגדרת כברירת מחדל בפרויקט. קובץ מקור מזוהה באופן ייחודי על ידי השילוב של file_path ו־file_tag_name.

תגובות

תגובת הצלחה

200 OKapplication/zip202 AcceptedRetry-After: 30
{
  "status": "processing",
  "message": "Translations are still in progress. Please retry after the specified delay.",
  "retry_after": 30
}

PTC מעבדת תרגומים באופן אסינכרוני. בדרך כלל ישנה המתנה קצרה בין העלאת קובץ מקור לבין הפיכת התרגומים לזמינים להורדה.

כאשר זה קורה, המתינו את מספר השניות המצוין ב־Retry-After.

תגובות שגיאה

קובץ המקור לא נמצא
404 Not Found
{
  "error": "Source file not found"
}
אין תרגומים זמינים
404 Not Found
{
  "error": "No translations are available for this source file"
}
לא מורשה
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
גישה נדחתה
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}
פרמטרים לא חוקיים
422 Unprocessable Entity
{
  "error": "Invalid parameters provided."
}

בקשות לדוגמה

בקשה בסיסית:

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/download_translations?file_path=locales/en.po" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -o translations.zip

בקשה עם תגית קובץ:

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/download_translations?file_path=locales/en.po&file_tag_name=frontend" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -o frontend-translations.zip

דוגמאות קוד

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/download_translations?file_path=locales/en.po&file_tag_name=frontend" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -o translations.zip
# 200 -> saves the zip; 202 -> {"status":"processing","retry_after":N} (retry later);
# 404 -> {"error":"No translations are available for this source file"}

העלאת קובצי מקור באצווה

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

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

מידע נוסף

  • אם קובץ תואם לקובץ מקור קיים, הוא מתעדכן בתוכן החדש, והתרגומים מופעלים מחדש.
  • אם קובץ נתמך אך אינו תואם לאף קובץ מקור קיים, הוא מתווסף לרשימה not_found_files ומתעלמים ממנו.
  • קבצים בפורמטים שאינם נתמכים מופיעים תחת unsupported_files ומתעלמים מהם.
  • קבצים עם תוכן לא חוקי מופיעים גם הם תחת unsupported_files ומתעלמים מהם.
  • עיבוד של קובצי ZIP גדולים עשוי להימשך זמן רב יותר. קבצים מעובדים אחד אחד כדי לנהל משאבים, ולכן מומלץ לפצל העלאות גדולות מאוד (יותר מ־100 קבצים) לאצוות קטנות יותר. כל הקבצים בקובץ ה־ZIP מוגדרים לתרגום אוטומטי.
  • קובץ ה־ZIP המועלה חייב להיות תקין וקריא. כל הקבצים בתוכו חייבים להיות בפורמט נתמך. שמות הקבצים לא צריכים לכלול תווים מיוחדים שעלולים לגרום לבעיות בנתיב.
  • אם סופק callback_url, נשלחת בקשת POST עבור כל קובץ מקור שעובד, יחד עם התוצאות שלו.

בקשת HTTP

POST https://app.ptc.wpml.org/api/v1/source_files/bulk

פרמטרים

פרמטר סוג חובה תיאור
zip_file file כן קובץ ZIP המכיל את קובצי המקור להעלאה. עליו להיות קובץ ZIP תקין.
file_tag_name string לא שם תגית הקובץ שתשויך לכל קובצי המקור בארכיון. אם לא צוין, ייעשה שימוש בתגית הקובץ המוגדרת כברירת מחדל בפרויקט. כל קובץ מקור מזוהה באופן ייחודי על ידי השילוב של file_path ו־file_tag_name.
callback_url string לא כתובת ה־URL שמקבלת התראות webhook עם עיבודו של כל קובץ.

מבנה קובץ ZIP צפוי

קובץ ה־ZIP יכול להכיל קובצי מקור בכל מבנה תיקיות שהוא. מבנה התיקיות נשמר, והקבצים מעובדים באופן רקורסיבי.

דוגמה למבנה ZIP:

source-files.zip
├── locales/
│   ├── messages-en.po
│   ├── validation-en.po
│   └── admin-en.po
├── frontend/
│   ├── components-en.json
│   └── pages-en.json
│   └── not-found-en.json
├── app-strings-en.properties
└── readme.txt (will be ignored)

סוגי קבצים נתמכים:

  • JSON: קובצי .json
  • Gettext: קובצי .po, .pot
  • Properties: קובצי .properties
  • YAML: קובצי .yml, .yaml
  • XML: קובצי .xml
  • Strings: קובצי .strings
  • XLIFF: קובצי .xliff, .xlf
  • CSV: קובצי .csv
  • PHP: קובצי .php

תגובות

תגובת הצלחה

200 OKapplication/json
{
  "success": true,
  "file_tag": {
      "id": 456,
      "name": "backend"
  },
  "processed_files": [
    {
      "id": 123,
      "file_path": "locales/messages-en.po",
      "created_at": "2024-01-15T10:30:00.000Z",
      "file_tag": {
        "id": 456,
        "name": "backend"
      }
    },
    {
      "id": 124,
      "file_path": "locales/validation-en.po",
      "created_at": "2024-01-15T10:30:05.000Z",
      "file_tag": {
        "id": 456,
        "name": "backend"
      }
    }
  ],
  "unsupported_files": [
    "readme.txt",
    "config.ini"
  ],
  "not_found_files": ["frontend/not-found-en.json"]
}
סכמת התגובה
שדה סוג תיאור
success boolean האם פעולת ההעלאה באצווה הצליחה.
file_tag object פרטי תגית הקובץ.
file_tag.id integer מזהה תגית הקובץ.
file_tag.name string שם תגית הקובץ.
processed_files array[object] מערך של קובצי מקור שעובדו בהצלחה.
processed_files[].id integer המזהה הייחודי של קובץ המקור שנוצר.
processed_files[].file_path string הנתיב של קובץ המקור, תוך שמירה על מבנה ה־ZIP המקורי.
processed_files[].created_at string חותמת זמן בפורמט ISO 8601 המציינת מתי נוצר קובץ המקור.
processed_files[].file_tag object פרטי תגית הקובץ.
processed_files[].file_tag.id integer מזהה תגית הקובץ.
processed_files[].file_tag.name string שם תגית הקובץ.
unsupported_files array[string] מערך של שמות קבצים שאינם בפורמט נתמך.
not_found_files array[string] מערך של קבצים נתמכים שלא תאמו לאף קובץ מקור קיים והמערכת התעלמה מהם.

תגובות שגיאה

קובץ ZIP לא תקין

422 Unprocessable Entity
{
  "success": false,
  "error": "File format is invalid",
  "processed_files": [],
  "unsupported_files": []
}

העיבוד נכשל

422 Unprocessable Entity
{
  "success": false,
  "error": "Failed to process ZIP archive",
  "processed_files": [],
  "unsupported_files": []
}

לא מורשה

401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}

גישה נדחתה

403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

Webhook Callback

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

גוף בקשת ה־Callback (לכל קובץ):

{
  "source_file_id": 123,
  "status": "completed",
  "file_tag_name": "backend",
  "download_url": "https://app.ptc.wpml.org/api/v1/source_files/download_translations?file_path=locales/messages-en.po&file_tag_name=backend",
  "file_path": "locales/messages-en.po"
}

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

העלאה בסיסית באצווה:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files/bulk" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "zip_file=@source-files.zip" \
  -F "file_tag_name=backend"

בקשה עם callback URL:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files/bulk" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "zip_file=@translations.zip" \
  -F "file_tag_name=localization" \
  -F "callback_url=https://your-app.com/webhooks/bulk-complete"

דוגמאות קוד

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files/bulk" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "zip_file=@source-files.zip" \
  -F "file_tag_name=backend" \
  -F "callback_url=https://your-app.com/webhooks/complete"
הבא:

איתור פורמטים נתמכים ושפות יעד באמצעות ה־API →