Übersetzungen über die API anfordern und abrufen

Verwenden Sie diese API, um Inhalte zur Übersetzung zu senden, deren Fortschritt zu verfolgen und die Übersetzungen in allen Zielsprachen abzurufen.

Diese API akzeptiert JSON-strukturierte Inhalte, wobei die ursprüngliche Struktur und die Schlüssel erhalten bleiben. Sie übersetzt nur Textwerte und lässt Zahlen, Booleans, Nullwerte und andere Nicht-Textwerte unverändert.

Inhaltsübersetzungen erstellen

Erstellt einen neuen Übersetzungsauftrag aus JSON-strukturierten Daten.

Der Endpunkt bewahrt die ursprüngliche Hierarchie der Schlüssel und Arrays Ihrer Inhalte, wobei nur Textwerte übersetzt werden und Zahlen, Booleans, Nullwerte und andere Nicht-Textwerte unverändert bleiben.

Es ist besonders nützlich für:

  • Inhaltsverwaltung – Lokalisierung dynamischer, in JSON strukturierter Inhalte
  • Konfigurationsdateien – Übersetzung von benutzerspezifischen Zeichenketten in Konfigurationsdaten
  • API-Antworten – Übersetzung strukturierter Antwort-Payloads
  • Dokumentation – Lokalisierung hierarchischer Hilfeinhalte oder Anleitungen

HTTP-Anfrage

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

Parameter

ParameterTypErforderlichBeschreibung
dataobjectJaDie JSON-strukturierten Daten zur Übersetzung. Sie können verschachtelte Objekte, Arrays und Zeichenkettenwerte enthalten.
nameZeichenketteNeinEin menschenlesbarer Name für den Übersetzungsauftrag. Wird er weggelassen, wird er automatisch generiert.
callback_urlZeichenketteNeinDie URL, die Webhook-Benachrichtigungen empfängt, wenn die Übersetzung abgeschlossen ist.
target_languagesarray[string]NeinDas Array der ISO-Codes für Zielsprachen. Wird es weggelassen, werden Übersetzungen für alle projektkonfigurierten Sprachen erstellt.
Weitere Informationen finden Sie in der API für verfügbare Zielsprachen.

Beispiel für den Anfragetext

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

Erfolgreiche Antwort

  • Code: 201 Created
  • Inhaltstyp: application/json
{
  "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

FeldTypBeschreibung
idZahlDer eindeutige Bezeichner des Inhaltsübersetzungsauftrags.
nameZeichenketteDer Auftragsname (automatisch generiert, falls nicht angegeben).
statusZeichenketteDer aktuelle Auftragsstatus (queued, processing, completed).
created_atZeichenketteDer ISO 8601 Zeitstempel, der angibt, wann der Auftrag erstellt wurde.
updated_atZeichenketteDer ISO 8601 Zeitstempel, der angibt, wann der Auftrag zuletzt aktualisiert wurde.

Fehlerantworten

Ungültige JSON-Daten
  • Code: 422 Unprocessable Entity
{
  "errors": {
    "data": ["Data must be a valid JSON object"]
  }
}
Ungültige Zielsprachen
  • Code: 422 Unprocessable Entity
{
  "errors": {
    "target_languages": ["Language codes [zh, xx] are not configured for this project"]
  }
}
Nicht autorisiert
  • Code: 401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Verboten
  • Code: 403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

JSON-Datenverarbeitung

Bei der Arbeit mit JSON-strukturierten Daten verarbeitet PTC die Daten wie folgt:

  • Struktur bleibt erhalten – Die ursprüngliche Hierarchie der Schlüssel und Verschachtelung bleibt unverändert
  • Nur Zeichenketten werden übersetzt – Zahlen, Booleans, Arrays und Nullwerte bleiben unverändert
  • Pfadbasierte Übersetzung – Jede übersetzbare Zeichenkette wird durch ihren JSON-Pfad identifiziert
  • Unterstützt Verschachtelung – Funktioniert mit tief verschachtelten Objekten und Arrays
  • Verarbeitet gemischte Datentypen – Nicht-Zeichenkettenwerte werden unverändert beibehalten

Beispiel für Datentransformation

Eingabe:

{
  "user": {
    "name": "Welcome User",
    "settings": {
      "theme": "Choose Theme",
      "count": 5,
      "enabled": true
    }
  }
}

: Verarbeitungsergebnis:

  • user.name: „Willkommen Benutzer“ → Wird übersetzt
  • user.settings.theme: „Theme auswählen“ → Wird übersetzt
  • user.settings.count: 5 → Bleibt unverändert
  • user.settings.enabled: true → Bleibt unverändert

Übersetzungs-Workflow

  1. Validierung: JSON-Struktur und Zielsprachen werden geprüft
  2. Quellendatei-Vorbereitung: JSON wird in ein internes Quellformat konvertiert
  3. Zeichenketten-Wiederverwendung durch Translation Memory: Alle übersetzbaren Zeichenketten werden extrahiert und im Translation Memory Ihres Projekts gespeichert, damit frühere Übersetzungen wiederverwendet werden können
  4. Auftrags-Warteschlange: Für jede Zielsprache wird ein Auftrag in die Warteschlange gestellt
  5. Verarbeitung: Die automatische Übersetzung läuft auf den extrahierten Zeichenketten
  6. Callback (optional): Ein Webhook wird gesendet, wenn alle Übersetzungen abgeschlossen sind, wenn callback_url angegeben ist

Webhook-Callback

Wenn ein callback_url angegeben ist, wird eine POST Anfrage gesendet, wenn der Auftrag abgeschlossen ist.

Callback-Anfragetext:

{
  "id": 1,
  "status": "completed",
  "translations_url": "https://app.ptc.wpml.org/api/v1/content_translation/1"
}

Unterstützte Datentypen

JSON-TypÜbersetzungsverhalten
stringIn Zielsprachen übersetzt
numberUnverändert beibehalten
booleanUnverändert beibehalten
nullUnverändert beibehalten
arrayRekursiv verarbeitet
objectRekursiv verarbeitet

Beispielanfragen

Grundlegende JSON-Übersetzung:

curl -X POST "https://app.ptc.wpml.org/api/v1/content_translation" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "welcome": "Welcome",
      "buttons": {
        "save": "Save",
        "cancel": "Cancel"
      }
    },
    "name": "UI Labels"
  }'

Mit spezifischen Zielsprachen:

curl -X POST "https://app.ptc.wpml.org/api/v1/content_translation" \
  -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

const translationData = {
  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 fetch('https://app.ptc.wpml.org/api/v1/content_translation', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(translationData)
});

const result = await response.json();
console.log('Translation job created:', result);

// Store the ID for later retrieval
const translationId = result.id;

import requests

translation_data = {
    "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"
}

headers = {
    'Content-Type': 'application/json'
}

response = requests.post('https://app.ptc.wpml.org/api/v1/content_translation', 
                        headers=headers, json=translation_data)
result = response.json()

print(f"Translation job created with ID: {result['id']}")
print(f"Status: {result['status']}")
<?php
$translationData = [
    '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($translationData),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json'
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

$result = json_decode($response, true);
echo "Translation job created with ID: " . $result['id'];
?>
const axios = require('axios');

const translationData = {
  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', translationData, {
  headers: {
    'Content-Type': 'application/json'
  }
});

console.log('Translation job created:', response.data);

// Monitor status
const checkStatus = async (id) => {
  const statusResponse = await axios.get(`https://app.ptc.wpml.org/api/v1/content_translation/${id}/status`);
  return statusResponse.data.status;
};

Inhaltsübersetzungen abrufen

Ruft den ursprünglichen Inhalt und alle übersetzten Versionen für einen bestimmten Inhaltsübersetzungsauftrag ab.

Die Antwort bewahrt Ihre Eingabestruktur: Sie gibt ein Quellobjekt plus ein Objekt pro Zielsprache zurück (geschlüsselt nach Sprachcode wie es, fr, de).

HTTP-Anfrage

GET https://app.ptc.wpml.org/api/v1/content_translation/{id}

Pfadparameter

ParameterTypErforderlichBeschreibung
idGanzzahlJaDer eindeutige Bezeichner des abzurufenden Inhaltsübersetzungsauftrags.

Antworten

Erfolgreiche Antwort

  • Code: 200 OK
  • Inhaltstyp: application/json
{
  "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

FeldTypBeschreibung
sourceobjectDer ursprüngliche Quellinhalt in derselben verschachtelten Struktur wie übermittelt.
{language_code}objectDer übersetzte Inhalt für jede Zielsprache, geschlüsselt nach ihrem ISO-Code (z. B. es, fr, de), mit derselben Struktur wie die Quelle.
Weitere Informationen finden Sie in der API für verfügbare Zielsprachen.

Fehlerantworten

Inhaltsübersetzung nicht gefunden
  • Code: 404 Not Found
{
  "error": "Content translation not found"
}
Nicht autorisiert
  • Code: 401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Verboten
  • Code: 403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

Beispielanfragen

Grundlegende Anfrage:

curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/123" \
  -H "Content-Type: application/json"

Codebeispiele

const contentTranslationId = 123;

const response = await fetch(`https://app.ptc.wpml.org/api/v1/content_translation/${contentTranslationId}`, {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

// Access source content
console.log('Source title:', data.source.app.title);

// Access translated content
console.log('Spanish title:', data.es.app.title);
console.log('French title:', data.fr.app.title);

// Iterate through all languages
Object.keys(data).forEach(langCode => {
  if (langCode !== 'source') {
    console.log(`${langCode} translation:`, data[langCode]);
  }
});
import requests

content_translation_id = 123
headers = {
    'Content-Type': 'application/json'
}

response = requests.get(f'https://app.ptc.wpml.org/api/v1/content_translation/{content_translation_id}', 
                       headers=headers)
data = response.json()

# Access source content
source_data = data['source']
print("Source content:", source_data)

# Access translations
for lang_code, translation in data.items():
    if lang_code != 'source':
        print(f"{lang_code.upper()} translation:", translation)
<?php
$content_translation_id = 123;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://app.ptc.wpml.org/api/v1/content_translation/{$content_translation_id}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json'
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

$data = json_decode($response, true);

// Access source content
$sourceData = $data['source'];
echo "Source content: " . json_encode($sourceData, JSON_PRETTY_PRINT) . "\n";

// Access translations
foreach ($data as $langCode => $translation) {
    if ($langCode !== 'source') {
        echo strtoupper($langCode) . " translation: " . json_encode($translation, JSON_PRETTY_PRINT) . "\n";
    }
}
?>
const axios = require('axios');

const contentTranslationId = 123;

const response = await axios.get(`https://app.ptc.wpml.org/api/v1/content_translation/${contentTranslationId}`, {
  headers: {
    'Content-Type': 'application/json'
  }
});

const data = response.data;

// Function to traverse nested objects
function extractStrings(obj, path = '') {
  const strings = [];
  for (const [key, value] of Object.entries(obj)) {
    const currentPath = path ? `${path}.${key}` : key;
    if (typeof value === 'string') {
      strings.push({ path: currentPath, value });
    } else if (typeof value === 'object') {
      strings.push(...extractStrings(value, currentPath));
    }
  }
  return strings;
}

// Extract all translatable strings
const sourceStrings = extractStrings(data.source);
console.log('Source strings:', sourceStrings);

// Compare with translations
Object.keys(data).forEach(langCode => {
  if (langCode !== 'source') {
    const translatedStrings = extractStrings(data[langCode]);
    console.log(`${langCode} strings:`, translatedStrings);
  }
});

Status der Inhaltsübersetzung abrufen

Ruft den aktuellen Status eines bestimmten Inhaltsübersetzungsauftrags ab.

Die Antwort spiegelt den Gesamtfortschritt wider und gibt an, ob die Übersetzung in der Warteschlange, in Bearbeitung, abgeschlossen oder fehlgeschlagen ist.

HTTP-Anfrage

GET https://app.ptc.wpml.org/api/v1/content_translation/{id}/status

Pfadparameter

ParameterTypErforderlichBeschreibung
idGanzzahlJaDie eindeutige Kennung des zu überprüfenden Inhaltsübersetzungsauftrags.

Antworten

Erfolgreiche Antwort

  • Code: 200 OK
  • Inhaltstyp: application/json
{
  "status": "completed",
  "completeness": 100
}
Antwortschema
FeldTypBeschreibung
statusZeichenketteDer aktuelle Übersetzungsstatus. Mögliche Statuswerte sind: queued, in_progress, completed, failed, status_unknown.
completenessZahlDer Prozentsatz der übersetzten Zeichenketten (0–100). Berechnet als (completed_translatable_strings / total_translatable_strings) × 100.
Statuswerte
StatusBeschreibung
queuedDie Übersetzung wurde in die Warteschlange gestellt und wartet auf die Bearbeitung.
in_progressDie Übersetzung wird gerade bearbeitet.
completedDie Übersetzung wurde erfolgreich abgeschlossen.
failedDie Übersetzung ist aufgrund eines Fehlers fehlgeschlagen.
status_unknownDer Übersetzungsstatus ist unbekannt oder kann noch nicht ermittelt werden.

Fehlerantworten

  • Code: 404 Not Found

Mögliche Ursachen:

  • Es existiert keine Inhaltsübersetzung mit der angegebenen ID
  • Der Übersetzungsauftrag 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
}
GET https://app.ptc.wpml.org/api/v1/content_translation/{id}/status
{
  "status": "in_progress",
  "completeness": 70
}
curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/123/status" \
  -H "Authorization: Bearer your-api-token"
{
  "status": "completed",
  "completeness": 100
}

Nach oben scrollen