PTC

Ü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.

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_translation

Parameter

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

201 Createdapplication/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

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
422 Unprocessable Entity
{
  "errors": {
    "data": ["Data must be a valid JSON object"]
  }
}
Ungültige Zielsprachen
422 Unprocessable Entity
{
  "errors": {
    "target_languages": ["Language codes [zh, xx] are not configured for this project"]
  }
}
Nicht autorisiert
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Verboten
403 Forbidden
{
  "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 übersetzt
  • user.settings.theme: „Choose Theme“ → 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 überprüft
  2. Vorbereitung der Quelldatei: JSON wird in ein internes Quellformat konvertiert
  3. 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
  4. Jobs in Warteschlange einreihen: Für jede Zielsprache wird ein Job in die Warteschlange eingereiht
  5. Verarbeitung: Die automatische Übersetzung wird für die extrahierten Strings ausgeführt
  6. Callback (optional): Ein Webhook wird gesendet, wenn alle Übersetzungen abgeschlossen sind, falls callback_url angegeben 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"

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

200 OKapplication/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

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
404 Not Found
{
  "error": "Content translation not found"
}
Nicht autorisiert
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Verboten
403 Forbidden
{
  "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"

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}/status

Pfadparameter

Parameter Typ Erforderlich Beschreibung
id integer Ja Der eindeutige Bezeichner des zu prüfenden Inhaltsübersetzungsjobs.

Antworten

Erfolgsantwort

200 OKapplication/json
{
  "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

404 Not Found

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
}