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 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 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_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 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

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 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
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 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 ü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 geprüft
  2. Vorbereitung der Quelldatei: JSON wird in ein internes Quellformat konvertiert
  3. 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
  4. Einreihen in die Warteschlange: Für jede Zielsprache wird ein Job in die Warteschlange eingereiht
  5. Verarbeitung: Die automatische Übersetzung wird auf den 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, 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"

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

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

Codebeispiele

curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/123" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

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

Pfadparameter

Parameter Typ Erforderlich Beschreibung
id integer Ja Die eindeutige Kennung des zu überprü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, 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

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
}