Übersetzungen über die API anfordern und abrufen
Verwenden Sie diese API, um Inhalte zur Übersetzung zu senden, den Fortschritt zu verfolgen und die Übersetzungen in allen Zielsprachen abzurufen.
Diese API akzeptiert JSON-strukturierte Inhalte und behält die ursprüngliche Struktur und Keys bei. Sie übersetzt nur Textwerte; Zahlen, Booleans, Nullwerte und andere Nicht-Textwerte bleiben unverändert.
API-Quicklinks
Inhaltsübersetzungen erstellen
Erstellt einen neuen Übersetzungsjob aus JSON-strukturierten Daten.
Der Endpunkt behält die ursprüngliche Hierarchie der Keys und Arrays Ihrer Inhalte bei und übersetzt nur Textwerte, während Zahlen, Booleans, Nullwerte und andere Nicht-Textwerte unverändert bleiben.
Dies ist besonders nützlich für:
- Content-Management – Lokalisieren von in JSON strukturierten dynamischen Inhalten
- Konfigurationsdateien – Übersetzen von benutzerseitigen Strings in Konfigurationsdaten
- API-Antworten – Übersetzen von strukturierten Antwort-Payloads
- Dokumentation – Lokalisieren von hierarchischen Hilfeinhalten oder Leitfäden
Eine vollständige Rails-Implementierung dieses Workflows finden Sie unter Übersetzen von dynamischen Inhalten in Rails mit der PTC-API.
HTTP-Request
POST https://app.ptc.wpml.org/api/v1/content_translationParameter
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
data |
object | Ja | Die zu übersetzenden JSON-strukturierten Daten. Diese können verschachtelte Objekte, Arrays und String-Werte enthalten. |
name |
string | Nein | Ein lesbarer Name für den Übersetzungsjob. Wenn dieser weggelassen wird, wird automatisch einer generiert. |
callback_url |
string | Nein | Die URL, die Webhook-Benachrichtigungen empfängt, wenn die Übersetzung abgeschlossen ist. |
target_languages |
array[string] | Nein | Das Array mit ISO-Codes für Zielsprachen. Wenn dies weggelassen wird, werden Übersetzungen für alle im Projekt konfigurierten Sprachen erstellt. Weitere Informationen finden Sie unter API für verfügbare Zielsprachen. |
Beispiel für Request-Body
{
"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"]
}Antworten
Erfolgsantwort
{
"id": 123,
"name": "App UI Translations",
"status": "queued",
"created_at": "2024-01-15T10:30:00.000Z",
"updated_at": "2024-01-15T10:30:00.000Z"
}Antwortschema
| Feld | Typ | Beschreibung |
|---|---|---|
id |
number | Die eindeutige Kennung des Inhaltsübersetzungsjobs. |
name |
string | Der Job-Name (wird automatisch generiert, falls nicht angegeben). |
status |
string | Der aktuelle Job-Status (queued, processing, completed). |
created_at |
string | Der ISO-8601-Zeitstempel, der angibt, wann der Job erstellt wurde. |
updated_at |
string | Der ISO-8601-Zeitstempel, der angibt, wann der Job zuletzt aktualisiert wurde. |
Fehlerantworten
Ungültige JSON-Daten
{
"errors": {
"data": ["Data must be a valid JSON object"]
}
}Ungültige Zielsprachen
{
"errors": {
"target_languages": ["Language codes [zh, xx] are not configured for this project"]
}
}Nicht autorisiert
{
"error": "Unauthorized access. Please provide a valid API token."
}Verboten
{
"error": "Access denied. Insufficient permissions."
}Verarbeitung von JSON-Daten
Bei der Arbeit mit JSON-strukturierten Daten verarbeitet die PTC die Daten wie folgt:
- Struktur bleibt erhalten – Die ursprüngliche Hierarchie der Keys und Verschachtelungen bleibt unverändert
- Nur Strings werden übersetzt – Zahlen, Booleans, Arrays und Nullwerte werden so beibehalten, wie sie sind
- Pfadbasierte Übersetzung – Jeder übersetzbare String wird durch seinen JSON-Pfad identifiziert
- Unterstützt Verschachtelung – Funktioniert mit tief verschachtelten Objekten und Arrays
- Verarbeitet gemischte Datentypen – Nicht-String-Werte bleiben ohne Änderung erhalten
Beispiel für Datentransformation
Eingabe:
{
"user": {
"name": "Welcome User",
"settings": {
"theme": "Choose Theme",
"count": 5,
"enabled": true
}
}
}Verarbeitungsergebnis:
user.name: „Welcome User“ → Wird übersetztuser.settings.theme: „Choose Theme“ → Wird übersetztuser.settings.count:5 → Bleibt unverändertuser.settings.enabled:true → Bleibt unverändert
Übersetzungs-Workflow
- Validierung: JSON-Struktur und Zielsprachen werden überprüft
- Vorbereitung der Quelldatei: JSON wird in ein internes Quellformat konvertiert
- Wiederverwendung von Strings durch translation memory: Alle übersetzbaren Strings werden extrahiert und im translation memory Ihres Projekts gespeichert, sodass frühere Übersetzungen wiederverwendet werden können
- Einreihung in die Warteschlange: Ein Job wird für jede Zielsprache in Warteschlange gestellt
- Verarbeitung: Die automatische Übersetzung wird für die extrahierten Strings ausgeführt
- Callback (optional): Ein Webhook wird gesendet, wenn alle Übersetzungen abgeschlossen sind, sofern
callback_urlangegeben ist
Webhook-Callback
Wenn eine callback_url angegeben ist, wird ein POST-Request gesendet, sobald der Job abgeschlossen ist.
Body des Callback-Requests:
{
"id": 1,
"status": "completed",
"translations_url": "https://app.ptc.wpml.org/api/v1/content_translation/1"
}Unterstützte Datentypen
| JSON-Typ | Übersetzungsverhalten |
|---|---|
string |
Wird in die Zielsprachen übersetzt |
number |
Bleibt unverändert erhalten |
boolean |
Bleibt unverändert erhalten |
null |
Bleibt unverändert erhalten |
array |
Wird rekursiv verarbeitet |
object |
Wird rekursiv verarbeitet |
Beispiel-Requests
Einfache JSON-Übersetzung:
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"
}'Mit bestimmten Zielsprachen:
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"
}'Code-Beispiele
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)`);Inhaltsübersetzungen abrufen
Ruft den ursprünglichen Inhalt und alle übersetzten Versionen für einen bestimmten Inhaltsübersetzungsjob ab.
Die Antwort behält Ihre Eingabestruktur bei: Sie gibt ein Quellobjekt sowie ein Objekt pro Zielsprache zurück (mit dem Sprachcode als Key, z. B. es, fr, de).
HTTP-Request
GET https://app.ptc.wpml.org/api/v1/content_translation/{id}Pfadparameter
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
id |
integer | Ja | Die eindeutige Kennung des Inhaltsübersetzungsjobs, der abgerufen werden soll. |
Antworten
Erfolgsantwort
{
"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"
}
}
}
}Antwortschema
| Feld | Typ | Beschreibung |
|---|---|---|
source |
object | Der ursprüngliche Quellinhalt in derselben verschachtelten Struktur wie bei der Übermittlung. |
{language_code} |
object | Der übersetzte Inhalt für jede Zielsprache, mit dem jeweiligen ISO-Code als Key (zum Beispiel es, fr, de) und derselben Struktur wie die Quelle. Weitere Informationen finden Sie unter API für verfügbare Zielsprachen. |
Fehlerantworten
Inhaltsübersetzung nicht gefunden
{
"error": "Content translation not found"
}Nicht autorisiert
{
"error": "Unauthorized access. Please provide a valid API token."
}Verboten
{
"error": "Access denied. Insufficient permissions."
}Beispiel-Requests
Einfacher Request:
curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/123" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json"Code-Beispiele
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 Content Translation Status abrufen
Ruft den aktuellen Status eines bestimmten Inhaltsübersetzungsjobs ab.
Die Antwort spiegelt den Gesamtfortschritt wider und enthält die Angabe, ob die Übersetzung in Warteschlange ist, in Bearbeitung ist, abgeschlossen wurde oder fehlgeschlagen ist.
HTTP-Request
GET https://app.ptc.wpml.org/api/v1/content_translation/{id}/statusPfadparameter
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
id |
integer | Ja | Die eindeutige Kennung des Inhaltsübersetzungsjobs, der überprüft werden soll. |
Antworten
Erfolgsantwort
{
"status": "completed",
"completeness": 100
}Antwortschema
| Feld | Typ | Beschreibung |
|---|---|---|
status |
string | Der aktuelle Übersetzungsstatus. Mögliche Statuswerte sind: draft, queued, in_progress, completed, failed, out_of_credit und null. |
completeness |
number | Der Prozentsatz der übersetzten Strings (0–100). Wird berechnet als (completed_translatable_strings / total_translatable_strings) × 100. |
Statuswerte
| Status | Beschreibung |
|---|---|
draft |
Die Quelldatei ist registriert, aber es ist noch keine Datei angehängt, daher gibt es nichts zu übersetzen. |
queued |
Die Übersetzung wurde in Warteschlange gestellt und wartet auf die Verarbeitung. |
in_progress |
Die Übersetzung wird derzeit verarbeitet. |
completed |
Die Übersetzung wurde erfolgreich abgeschlossen. |
failed |
Die Übersetzung ist aufgrund eines Fehlers fehlgeschlagen. |
out_of_credit |
Die Übersetzung wurde gestoppt, da dem Projekt die Credits ausgegangen sind. Dies ist ein Endzustand – der Durchlauf wird nicht von selbst fortgesetzt, sobald Credits hinzugefügt werden. Fragen Sie ihn daher genauso ab wie bei failed. |
null |
Noch keine Übersetzung hat einen der oben genannten Status erreicht. Erwarten Sie dies direkt nach dem Erstellen einer Inhaltsübersetzung und behandeln Sie es als „nicht gestartet“ und nicht als Fehler. |
Fehlerantworten
Mögliche Ursachen:
- Es existiert keine Inhaltsübersetzung mit der angegebenen ID
- Der Übersetzungsjob gehört nicht zum authentifizierten Projekt
Beispiel
curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/123/status" \
-H "Authorization: Bearer YOUR_API_TOKEN"Antwort:
{
"status": "completed",
"completeness": 100
}Antwort, während der Job noch ausgeführt wird:
{
"status": "in_progress",
"completeness": 70
}{
"status": "completed",
"completeness": 100
}