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 belässt Zahlen, boolesche Werte, 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 belässt Zahlen, boolesche Werte, 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 von strukturierten Antwort-Nutzdaten
  • Dokumentation – Lokalisierung von hierarchischen Hilfeinhalten 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 Callback-URL, die Webhook-Benachrichtigungen empfängt, wenn die Übersetzung abgeschlossen ist.
target_languages array[string] Nein Das Array von 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 den 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 Jobname (automatisch generiert, falls nicht angegeben).
status string Der aktuelle Jobstatus (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

Wenn Sie mit JSON-strukturierten Daten arbeiten, 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, boolesche Werte, Arrays und Nullwerte werden unverändert beibehalten
  • 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 ü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. Einreihung in die Warteschlange: 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, sofern 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 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"
  }'

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

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, 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, in der er übermittelt wurde.
{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 sich die Übersetzung in der Warteschlange befindet, in Bearbeitung ist, abgeschlossen ist 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 umfassen: queued, in_progress, completed, failed, status_unknown.
completeness number Der Prozentsatz der übersetzten Strings (0–100). Wird berechnet als (completed_translatable_strings / total_translatable_strings) × 100.
Statuswerte
Status Beschreibung
queued Die Übersetzung wurde in die Warteschlange eingereiht 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 ermittelt werden.

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
}