Ü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 die Keys bei. Sie übersetzt nur Textwerte und lässt Zahlen, Booleans, Nullwerte und andere Nicht-Text-Werte unverändert.
API-Quicklinks
- Inhaltsübersetzungen erstellen
- Inhaltsübersetzungen abrufen
- Den Übersetzungsstatus von Inhalten abrufen
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, übersetzt nur Textwerte und lässt Zahlen, Booleans, Nullwerte und andere Nicht-Text-Werte unverändert.
Dies ist besonders nützlich für:
- Content-Management – Lokalisierung dynamischer Inhalte, die in JSON strukturiert sind
- Konfigurationsdateien – Übersetzung von benutzerseitigen Strings in Konfigurationsdaten
- API-Antworten – Übersetzung strukturierter Response-Payloads
- Dokumentation – Lokalisierung hierarchischer Hilfeinhalte oder Leitfäden
Für eine vollständige Rails-Implementierung dieses Workflows siehe Übersetzung dynamischer Inhalte 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. Sie können verschachtelte Objekte, Arrays und String-Werte enthalten. |
name |
string | Nein | Ein für Menschen 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 der ISO-Codes für die 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 | Der eindeutige Bezeichner des Inhaltsübersetzungsjobs. |
name |
string | Der Name des Jobs (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
- Umgang mit gemischten 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
- Jobs in Warteschlange einreihen: Für jede Zielsprache wird ein Job in die Warteschlange eingereiht
- Verarbeitung: Die automatische Übersetzung wird für die extrahierten Strings ausgeführt
- Callback (optional): Ein Webhook wird gesendet, wenn alle Übersetzungen abgeschlossen sind, falls
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 |
Wird unverändert beibehalten |
boolean |
Wird unverändert beibehalten |
null |
Wird unverändert beibehalten |
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 wie es, fr, de).
HTTP-Request
GET https://app.ptc.wpml.org/api/v1/content_translation/{id}Pfadparameter
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
id |
integer | Ja | Der eindeutige Bezeichner des abzurufenden Inhaltsübersetzungsjobs. |
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 übermittelt. |
{language_code} |
object | Der übersetzte Inhalt für jede Zielsprache, mit ihrem ISO-Code als Key (zum Beispiel es, fr, de), mit 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]);
});Den Übersetzungsstatus von Inhalten abrufen
Ruft den aktuellen Status eines bestimmten Inhaltsübersetzungsjobs ab.
Die Antwort spiegelt den Gesamtfortschritt wider und gibt an, ob die Übersetzung in der Warteschlange steht, 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 | Der eindeutige Bezeichner des zu prüfenden Inhaltsübersetzungsjobs. |
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, es ist jedoch noch keine Datei angehängt, sodass es nichts zu übersetzen gibt. |
queued |
Die Übersetzung wurde in die Warteschlange eingereiht und wartet auf ihre 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 Wörter ausgegangen sind. Dies ist ein Endzustand – der Durchlauf wird nicht von selbst fortgesetzt, sobald weitere Wörter hinzugefügt werden. Fragen Sie ihn daher genauso ab wie failed. |
null |
Noch hat keine Übersetzung einen der oben genannten Status erreicht. Erwarten Sie dies direkt nach der Erstellung 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
}