בקשה ואחזור של תרגומים דרך ה־API
השתמשו ב־API הזה כדי לשלוח תוכן לתרגום, לעקוב אחר ההתקדמות שלו, ולאחזר את התרגומים בכל שפות היעד.
ה־API הזה מקבל תוכן מובנה ב־JSON, ושומר על המבנה והמפתחות המקוריים. הוא מתרגם רק ערכי טקסט, ומשאיר מספרים, ערכים בוליאניים, ערכי null וערכים אחרים שאינם טקסט ללא שינוי.
קישורים מהירים ל־API
Create Content Translations
נקודת קצה זו יוצרת משימת תרגום חדשה מנתונים מובנים ב־JSON.
נקודת הקצה שומרת על ההיררכיה המקורית של המפתחות והמערכים בתוכן שלכם, מתרגמת רק ערכי טקסט ומשאירה מספרים, ערכים בוליאניים, ערכי null וערכים אחרים שאינם טקסט ללא שינוי.
היא שימושית במיוחד עבור:
- ניהול תוכן – לוקליזציה של תוכן דינמי המובנה ב־JSON
- קובצי תצורה – תרגום מחרוזות החשופות למשתמש בנתוני תצורה
- תגובות API – תרגום נתוני תגובה מובנים
- תיעוד – לוקליזציה של תוכן עזרה או מדריכים היררכיים
ליישום מלא של תהליך עבודה זה ב־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"]
}תגובות
תגובת הצלחה
{
"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 לא תקינים
{
"errors": {
"data": ["Data must be a valid JSON object"]
}
}שפות יעד לא תקינות
{
"errors": {
"target_languages": ["Language codes [zh, xx] are not configured for this project"]
}
}לא מורשה (Unauthorized)
{
"error": "Unauthorized access. Please provide a valid API token."
}אסור (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 → נשאר ללא שינוי
תהליך התרגום
- אימות: מבנה ה־JSON ושפות היעד נבדקים
- הכנת קובץ המקור: ה־JSON מומר לפורמט מקור פנימי
- שימוש חוזר במחרוזות דרך זיכרון תרגומי: כל המחרוזות הניתנות לתרגום מחולצות ונשמרות בזיכרון התרגומי של הפרויקט שלכם, כך שניתן להשתמש מחדש בתרגומים קודמים
- הכנסת משימות לתור: משימה נכנסת לתור עבור כל שפת יעד
- עיבוד: תרגום אוטומטי מורץ על המחרוזות שחולצו
- 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"require 'net/http'
require 'uri'
require 'json'
uri = URI('https://app.ptc.wpml.org/api/v1/content_translation')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
data: { app: { title: 'My Application',
navigation: { home: 'Home', about: 'About Us' } } },
name: 'App Translations',
target_languages: %w[es fr de],
callback_url: 'https://your-app.com/webhooks/complete'
}.to_json
response = http.request(request)
id = JSON.parse(response.body)['id']
puts "Translation job created with ID: #{id}"
# Poll the status endpoint for progress (status is set there, not on create)
status_uri = URI("https://app.ptc.wpml.org/api/v1/content_translation/#{id}/status")
status_request = Net::HTTP::Get.new(status_uri)
status_request['Authorization'] = 'Bearer YOUR_API_TOKEN'
status = JSON.parse(http.request(status_request).body)
puts "Status: #{status['status']} (#{status['completeness']}% complete)"import requests
headers = {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json'
}
payload = {
"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"
}
response = requests.post('https://app.ptc.wpml.org/api/v1/content_translation', headers=headers, json=payload)
translation_id = response.json()['id']
print(f"Translation job created with ID: {translation_id}")
# Poll the status endpoint for progress (status is set there, not on create)
status_response = requests.get(f'https://app.ptc.wpml.org/api/v1/content_translation/{translation_id}/status', headers=headers)
status = status_response.json()
print(f"Status: {status['status']} ({status['completeness']}% complete)")<?php
$payload = [
'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'
];
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'https://app.ptc.wpml.org/api/v1/content_translation',
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_API_TOKEN',
'Content-Type: application/json'
],
]);
$response = curl_exec($curl);
curl_close($curl);
$id = json_decode($response, true)['id'];
echo "Translation job created with ID: " . $id . "\n";
// Poll the status endpoint for progress (status is set there, not on create)
$statusCurl = curl_init();
curl_setopt_array($statusCurl, [
CURLOPT_URL => "https://app.ptc.wpml.org/api/v1/content_translation/{$id}/status",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_TOKEN'],
]);
$status = json_decode(curl_exec($statusCurl), true);
curl_close($statusCurl);
echo "Status: " . $status['status'] . " (" . $status['completeness'] . "% complete)";
?>import okhttp3.*;
OkHttpClient client = new OkHttpClient();
MediaType JSON = MediaType.parse("application/json");
String payload = "{"
+ "\"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\"}";
Request request = new Request.Builder()
.url("https://app.ptc.wpml.org/api/v1/content_translation")
.addHeader("Authorization", "Bearer YOUR_API_TOKEN")
.post(RequestBody.create(payload, JSON))
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());package main
import (
"bytes"
"fmt"
"io"
"net/http"
)
func main() {
payload := []byte(`{
"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"
}`)
req, _ := http.NewRequest("POST", "https://app.ptc.wpml.org/api/v1/content_translation", bytes.NewBuffer(payload))
req.Header.Add("Authorization", "Bearer YOUR_API_TOKEN")
req.Header.Add("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Text;
var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "YOUR_API_TOKEN");
var payload = @"{
""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""
}";
var body = new StringContent(payload, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://app.ptc.wpml.org/api/v1/content_translation", body);
var content = await response.Content.ReadAsStringAsync();
Console.WriteLine(content);const axios = require('axios');
const payload = {
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"
};
const response = await axios.post('https://app.ptc.wpml.org/api/v1/content_translation', payload, {
headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
});
const translationId = response.data.id;
console.log('Translation job created with ID:', translationId);
// Poll the status endpoint for progress (status is set there, not on create)
const status = await axios.get(`https://app.ptc.wpml.org/api/v1/content_translation/${translationId}/status`, {
headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
});
console.log(`Status: ${status.data.status} (${status.data.completeness}% complete)`);Get Content Translations
נקודת קצה זו מאחזרת את התוכן המקורי ואת כל הגרסאות המתורגמות עבור משימת תרגום תוכן ספציפית.
התגובה שומרת על מבנה הקלט שלכם: היא מחזירה אובייקט מקור (source) בתוספת אובייקט אחד לכל שפת יעד (מזוהה על ידי קוד השפה, כגון es, fr, de).
בקשת HTTP
GET https://app.ptc.wpml.org/api/v1/content_translation/{id}פרמטרי נתיב
| פרמטר | סוג | חובה | תיאור |
|---|---|---|---|
id |
integer | כן | המזהה הייחודי של משימת תרגום התוכן לאחזור. |
תגובות
תגובת הצלחה
{
"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 שפות יעד זמינות. |
תגובות שגיאה
תרגום התוכן לא נמצא
{
"error": "Content translation not found"
}לא מורשה (Unauthorized)
{
"error": "Unauthorized access. Please provide a valid API token."
}אסור (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"require 'net/http'
require 'uri'
uri = URI('https://app.ptc.wpml.org/api/v1/content_translation/123')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
response = http.request(request)
require 'json'
data = JSON.parse(response.body)
puts "Source: #{data['source']}"
data.each { |lang, translation| puts "#{lang}: #{translation}" unless lang == 'source' }import requests
headers = {
'Authorization': 'Bearer YOUR_API_TOKEN'
}
response = requests.get('https://app.ptc.wpml.org/api/v1/content_translation/123', headers=headers)
data = response.json()
print('Source:', data['source'])
for lang_code, translation in data.items():
if lang_code != 'source':
print(f"{lang_code}:", translation)<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'https://app.ptc.wpml.org/api/v1/content_translation/123',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_API_TOKEN'
],
]);
$response = curl_exec($curl);
curl_close($curl);
$data = json_decode($response, true);
foreach ($data as $langCode => $translation) {
echo strtoupper($langCode) . ": " . json_encode($translation) . "\n";
}
?>import okhttp3.*;
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://app.ptc.wpml.org/api/v1/content_translation/123")
.addHeader("Authorization", "Bearer YOUR_API_TOKEN")
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://app.ptc.wpml.org/api/v1/content_translation/123", nil)
req.Header.Add("Authorization", "Bearer YOUR_API_TOKEN")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
using System;
using System.Net.Http;
using System.Threading.Tasks;
var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "YOUR_API_TOKEN");
var response = await client.GetAsync("https://app.ptc.wpml.org/api/v1/content_translation/123");
var content = await response.Content.ReadAsStringAsync();
Console.WriteLine(content);const axios = require('axios');
const response = await axios.get('https://app.ptc.wpml.org/api/v1/content_translation/123', {
headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
});
const data = response.data;
console.log('Source:', data.source);
Object.keys(data).forEach(lang => {
if (lang !== 'source') console.log(`${lang}:`, data[lang]);
});Get the Content Translation Status
מאחזרת את הסטטוס הנוכחי של משימת תרגום תוכן ספציפית.
התגובה משקפת את ההתקדמות הכוללת וכוללת מידע האם התרגום נמצא בתור, בתהליך, הושלם או נכשל.
בקשת HTTP
GET https://app.ptc.wpml.org/api/v1/content_translation/{id}/statusפרמטרי נתיב
| פרמטר | סוג | חובה | תיאור |
|---|---|---|---|
id |
integer | כן | המזהה הייחודי של משימת תרגום התוכן לבדיקה. |
תגובות
תגובת הצלחה
{
"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 |
התרגום נעצר מכיוון שלפרויקט נגמרו המילים. זהו מצב סופי — ההרצה אינה מתחדשת מעצמה ברגע שמתווספות מילים נוספות, לכן בצעו עבורה תשאול כפי שהייתם עושים עבור failed. |
null |
אף תרגום לא הגיע עדיין לאף אחד מהסטטוסים שלעיל. צפו לזה מיד לאחר יצירת תרגום תוכן, והתייחסו לכך כאל ”לא התחיל“ במקום כאל שגיאה. |
תגובות שגיאה
סיבות אפשריות:
- לא קיים תרגום תוכן עם המזהה שצוין
- משימת התרגום אינה שייכת לפרויקט המאומת
דוגמה
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
}