Ü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 und lässt Zahlen, Booleans, Nullwerte und andere Nicht-Text-Werte unverändert.
API-Quicklinks
Inhaltsübersetzungen erstellen
Erstellt einen neuen Übersetzungsjob aus JSON-strukturierten Daten.
Der Endpunkt behält die ursprüngliche Hierarchie von 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
Eine vollständige Rails-Implementierung dieses Workflows finden Sie unter Ü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 menschenlesbarer Name für den Übersetzungsjob. Wenn weggelassen, 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 Zielsprachen. Wenn weggelassen, 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 (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 von Keys und Verschachtelungen bleibt unverändert
- Nur Strings werden übersetzt – Zahlen, Booleans, Arrays und Nullwerte werden 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 geprüft
- Vorbereitung der Quelldatei: JSON wird in ein internes Quellformat konvertiert
- Wiederverwendung von Strings durch das Translation Memory: Alle übersetzbaren Strings werden extrahiert und im Translation Memory Ihres Projekts gespeichert, sodass bereits vorhandene Übersetzungen wiederverwendet werden können
- Einreihen in die Warteschlange: Für jede Zielsprache wird ein Job in die Warteschlange eingereiht
- Verarbeitung: Die automatische Übersetzung wird auf den 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, wenn der Job abgeschlossen ist.
Callback-Request-Body:
{
"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 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"
}'Codebeispiele
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 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 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 dem jeweiligen ISO-Code als Key (zum Beispiel es, fr, de), in 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"Codebeispiele
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
Ruft den aktuellen Status eines bestimmten Inhaltsübersetzungsjobs ab.
Die Antwort spiegelt den Gesamtfortschritt wider und gibt an, 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 zu überprü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, hat aber 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, weil dem Projekt die Wörter ausgegangen sind. Dies ist ein Endzustand – der Durchlauf wird nicht von selbst fortgesetzt, wenn wieder Wörter hinzugefügt werden, fragen Sie ihn also ab, wie Sie es für failed tun würden. |
null |
Noch hat keine Übersetzung einen der obigen Status erreicht. Erwarten Sie dies direkt nach dem Erstellen einer Inhaltsübersetzung und behandeln Sie es als „nicht gestartet“ statt 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
}