PTC

Ü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 und bewahrt die ursprüngliche Struktur sowie die Keys. Es werden nur Textwerte übersetzt, während Zahlen, boolesche Werte, Nullwerte und andere Nicht-Text-Werte unverändert bleiben.

Content-Übersetzungen erstellen

Erstellt einen neuen Übersetzungsauftrag aus JSON-strukturierten Daten.

Der Endpunkt bewahrt die ursprüngliche Hierarchie Ihrer Keys und Arrays und übersetzt nur Textwerte, während Zahlen, boolesche Werte, Nullwerte und andere Nicht-Text-Werte unverändert bleiben.

Dies ist besonders nützlich für:

  • Content-Management – Lokalisierung von dynamischen Inhalten, die in JSON strukturiert sind
  • Konfigurationsdateien – Übersetzung von benutzerorientierten Strings in Konfigurationsdaten
  • API-Antworten – Übersetzung strukturierter Response-Payloads
  • Dokumentation – Lokalisierung hierarchischer Hilfeinhalte oder Anleitungen

Für eine vollständige Rails-Implementierung dieses Workflows lesen Sie bitte Dynamische Inhalte in Rails mit der PTC-API übersetzen.

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. Kann verschachtelte Objekte, Arrays und String-Werte enthalten.
name string Nein Ein lesbarer Name für den Übersetzungsauftrag. Falls weggelassen, wird automatisch einer generiert.
callback_url string Nein Die URL, die Webhook-Benachrichtigungen erhält, wenn die Übersetzung abgeschlossen ist.
target_languages array[string] Nein Das Array der ISO-Codes für Zielsprachen. Falls weggelassen, werden Übersetzungen für alle im Projekt konfigurierten Sprachen erstellt. Weitere Informationen finden Sie in der 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

Erfolgreiche Antwort

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

Antwort-Schema

Feld Typ Beschreibung
id number Die eindeutige Kennung des Content-Übersetzungsauftrags.
name string Der Name des Auftrags (automatisch generiert, falls nicht angegeben).
status string Der aktuelle Status des Auftrags (queued, processing, completed).
created_at string Der ISO-8601-Zeitstempel, der angibt, wann der Auftrag erstellt wurde.
updated_at string Der ISO-8601-Zeitstempel, der angibt, wann der Auftrag 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."
}

JSON-Datenverarbeitung

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

  • Struktur bleibt erhalten – Die ursprüngliche Hierarchie der Keys und Verschachtelungen bleibt unverändert
  • Nur Strings werden übersetzt – Zahlen, boolesche Werte, Arrays und Nullwerte werden so belassen, wie sie sind
  • Pfadbasierte Übersetzung – Jeder zu übersetzende 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 Modifikation erhalten

Beispiel für Datentransformation

Input:

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

Ergebnis der Verarbeitung:

  • 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 umgewandelt
  3. String-Wiederverwendung durch Translation Memory: Alle zu übersetzenden Strings werden extrahiert und in Ihrem Projekt-Translation-Memory gespeichert, damit frühere Übersetzungen wiederverwendet werden können
  4. Auftragswarteschlange: Für jede Zielsprache wird ein Auftrag in die Warteschlange gestellt
  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, sofern eine callback_url angegeben wurde

Webhook-Callback

Wenn eine callback_url angegeben wurde, wird ein POST-Request gesendet, sobald der Auftrag 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 spezifischen 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 (status stays
# "in_progress" until done — it is not set on the create response):
curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/CONTENT_TRANSLATION_ID/status" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Content-Übersetzungen abrufen

Ruft den ursprünglichen Inhalt und alle übersetzten Versionen für einen spezifischen Content-Übersetzungsauftrag ab.

Die Antwort bewahrt Ihre Input-Struktur: Sie gibt ein Quellobjekt (source) plus ein Objekt pro Zielsprache zurück (indiziert durch den Sprachcode, z. B. es, fr, de).

HTTP-Request

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

Pfad-Parameter

Parameter Typ Erforderlich Beschreibung
id integer Ja Die eindeutige Kennung des abzurufenden Content-Übersetzungsauftrags.

Antworten

Erfolgreiche Antwort

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

Antwort-Schema

Feld Typ Beschreibung
source object Der ursprüngliche Quellinhalt in derselben verschachtelten Struktur wie bei der Übermittlung.
{language_code} object Der übersetzte Inhalt für jede Zielsprache, indiziert durch ihren ISO-Code (zum Beispiel es, fr, de), mit derselben Struktur wie die Quelle. Weitere Informationen finden Sie in der API für verfügbare Zielsprachen.

Fehlerantworten

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

Status der Content-Übersetzung abrufen

Ruft den aktuellen Status eines spezifischen Content-Übersetzungsauftrags 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

Pfad-Parameter

Parameter Typ Erforderlich Beschreibung
id integer Ja Die eindeutige Kennung des zu prüfenden Content-Übersetzungsauftrags.

Antworten

Erfolgreiche Antwort

200 OKapplication/json
{
  "status": "completed",
  "completeness": 100
}
Antwort-Schema
Feld Typ Beschreibung
status string Der aktuelle Übersetzungsstatus. Mögliche Statuswerte sind: queued, in_progress, completed, failed, status_unknown.
completeness number Der Prozentsatz der übersetzten Strings (0–100). Berechnet als (completed_translatable_strings / total_translatable_strings) × 100.
Statuswerte
Status Beschreibung
queued Die Übersetzung wurde in die Warteschlange gestellt und wartet auf die Verarbeitung.
in_progress Die Übersetzung wird derzeit verarbeitet.
completed Die Übersetzung wurde erfolgreich abgeschlossen.
failed Die Übersetzung ist aufgrund eines Fehlers fehlgeschlagen.
status_unknown Der Übersetzungsstatus ist unbekannt oder kann noch nicht bestimmt werden.

Fehlerantworten

404 Not Found

Mögliche Ursachen:

  • Es existiert keine Content-Ü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
}

Antwort, während der Auftrag noch läuft:

{
  "status": "in_progress",
  "completeness": 70
}
{
  "status": "completed",
  "completeness": 100
}