PTC

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

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

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

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

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

תגיות קבצים

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

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

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

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

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

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

פרמטרי שאילתה (Query Parameters)

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

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

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


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

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

בקשת 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=locale/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
  }
}
סכימת תגובה

אובייקט קובץ מקור (Source File Object):

שדה סוג תיאור
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 הכתובת להורדת תרגומים עבור קובץ מקור זה.

אובייקט חלוקה לעמודים (Pagination Object):

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

תגובות שגיאה

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" \
  -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"

קבלת מחרוזות תרגום

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

נקודת קצה זו שימושית לשליפת תוכן שצריך לתרגם או שכבר תורגם. קובץ המקור מזוהה על ידי 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 סמן העמוד הנוכחי המשמש לחלוקה לעמודים.

תגובות שגיאה

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_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"

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

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

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

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

בקשת HTTP

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

פרמטרים

פרמטר סוג חובה תיאור
file_path string כן הנתיב שבו יש לאחסן את קובץ המקור בפרויקט. חייב להיות בעל סיומת נתמכת.
output_file_path string כן תבנית נתיב הפלט עבור קבצים מתורגמים. השתמשו ב־{{lang}} כמציין מיקום עבור קוד השפה.
translations array[object] לא קובצי תרגום קיימים מראש להעלאה לצד קובץ המקור. קבצים אלו יאוחסנו כפי שסופקו, והמחרוזות שלהם לא יתורגמו מחדש על ידי PTC. שימו לב שמתן תרגומים קיימים אינו מומלץ, שכן PTC מפיק תוצאות טובות יותר כאשר הוא יכול להשתמש בהקשר המלא של הפרויקט ולתרגם מאפס.
translations[].target_language_iso string כן קוד ה־ISO של שפת היעד עבור תרגום זה. ניתן למצוא את הרשימה המלאה של השפות הנתמכות וקודי ה־ISO שלהן בנקודת הקצה הצגת כל שפות היעד.
translations[].file file כן קובץ התרגום להעלאה.
additional_translation_files array[object] לא הגדרות קובצי פלט נוספים עבור פורמטים ספציפיים. כדי לראות אילו פורמטים תומכים בקובצי פלט נוספים, עיינו בנקודת הקצה הצגת פורמטי קבצים נתמכים. עבור פורמטים שאינם נתמכים, שדה זה יתעלם.
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 שם תגית הקובץ.

תגובות שגיאה

Validation Failed
422 Unprocessable Entity
{
  "success": false,
  "error": "Source file creation failed"
}
Unauthorized
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Forbidden
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"

בקשה עם URL לקריאה חוזרת (callback):

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file_path=src/locales/messages.po" \
  -F "output_file_path=locales/{lang}/messages.po" \
  -F "callback_url=https://your-app.com/webhooks/translation-complete"

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

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[mo]=locales/{lang}/messages.mo" \
  -F "additional_translation_files[json]=locales/{lang}/messages.json"

דוגמאות קוד

  • JavaScript (FormData)
  • Python (requests)
  • PHP (cURL)
  • Node.js (axios)
  • Callback Request Body
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"
}

עיבוד קובץ המקור

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

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

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

בקשת 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 שם תגית הקובץ.

תגובות שגיאה

Source File Not Found
422 Unprocessable Entity
{
  "errors": {
    "file": ["File format is invalid or not supported"]
  }
}
Unauthorized
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Forbidden
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

תהליך עבודה (Workflow)

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

Webhook Callback

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

גוף בקשת ה־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"

בקשה עם 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"

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

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

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


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

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

פעולה זו שימושית עבור:

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

בקשת 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.

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

אם אין תרגומים זמינים עבור הקובץ, הבקשה תחזיר שגיאת 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.

תגובות שגיאה

Source File Not Found
404 Not Found
{
  "error": "Source file not found"
}
No Translations Available
404 Not Found
{
  "error": "No translations are available for this source file"
}
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/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 available for this source file"}

העלאת קובצי מקור בכמות גדולה (Bulk)

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

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

מידע נוסף

  • אם קובץ תואם לקובץ מקור קיים, הוא מעודכן בתוכן החדש, ותרגומים מופעלים מחדש.
  • אם קובץ נתמך אך אינו תואם לאף קובץ מקור קיים, הוא מתווסף לרשימת not_found_files ומתעלמים ממנו.
  • קבצים בפורמטים שאינם נתמכים מופיעים תחת unsupported_files ומתעלמים מהם.
  • קבצים עם תוכן לא תקין מופיעים גם הם תחת unsupported_files ומתעלמים מהם.
  • עיבוד ארכיונים גדולים עשוי להימשך זמן רב יותר. קבצים מעובדים אחד אחד כדי לנהל משאבים, לכן מומלץ לפצל העלאות גדולות מאוד (יותר מ־100 קבצים) לקבוצות קטנות יותר. כל הקבצים בארכיון מוגדרים לתרגום אוטומטי.
  • קובץ ה־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] מערך של קבצים נתמכים שלא תאמו לאף קובץ מקור קיים וזכו להתעלמות.

תגובות שגיאה

Invalid ZIP File

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

Processing Failed

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

Unauthorized

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

Forbidden

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": "locale/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"

בקשה עם 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 ←