PTC

Quelldateien über die API hochladen und verwalten

Verwenden Sie diese API, um neue Quelldateien hochzuladen, veraltete zu ersetzen, den Übersetzungsfortschritt zu verfolgen und abgeschlossene Übersetzungen herunterzuladen.

Egal, ob Sie eine einzelne Datei verwalten oder einen Workflow der kontinuierlichen Lokalisierung automatisieren, diese API gibt Ihnen die volle Kontrolle über die Inhalte, die Sie zur Übersetzung senden, und darüber, wie Sie die Übersetzungen erhalten.

Wie die PTC-API Quelldateien identifiziert und organisiert

Die PTC-API verwendet ein flexibles System, das auf Datei-Tags und Dateipfaden basiert. Diese Parameter arbeiten zusammen, um sicherzustellen, dass jede Datei, die Sie hochladen, aktualisieren oder anfordern, klar definiert und einfach zu verwalten ist.

Datei-Tags

Datei-Tags sind eine flexible Möglichkeit, Quelldateien in Übersetzungsprojekten zu gruppieren und zu organisieren. Sie können sie wie Kategorien verwenden, um sie an Ihre Workflow-Anforderungen anzupassen. Beispielsweise können Datei-Tags Folgendes anzeigen:

  • Versionskontrolle: v1.0, beta, production
  • Feature-Branches: user-auth, dashboard-redesign
  • Anwendungskontext: mobile-app, admin-panel, marketing
  • Team-Zuständigkeit: frontend-team, content-team
  • Workflow-Status: approved, pending-review, priority-high

Namen von Datei-Tags sind in den meisten API-Operationen optional. Dennoch hat jede Quelldatei immer mindestens ein Tag. Ein Standard-Datei-Tag wird automatisch erstellt und zugewiesen, wenn ein Projekt eingerichtet wird. Dieses Standardverhalten hält Projekte auch bei einfachen Setups organisiert und ermöglicht es Ihnen gleichzeitig, bei Bedarf erweiterte Tagging-Strukturen aufzubauen.

Name des Datei-Tags + Dateipfad

Jede Quelldatei wird durch die Kombination aus dem Namen des Datei-Tags und dem Dateipfad eindeutig identifiziert.

  • Wenn Sie beim Hochladen oder Verarbeiten einer Datei kein benutzerdefiniertes Datei-Tag angeben, wird automatisch das Standard-Tag zugewiesen.
  • Der Tag-Name + Pfad einer Datei definieren zusammen ihre Identität. Diese Kombination stellt sicher, dass jede Datei innerhalb Ihres Projekts eindeutig ist, selbst wenn verschiedene Versionen oder Kontexte denselben Dateipfad verwenden.

Abfrageparameter

Beim Abrufen einer bestimmten Datei können zugehörige Endpunkte Abfrageparameter akzeptieren, wie zum Beispiel:

  • file_tag_name – Das mit der Datei verknüpfte Tag
  • file_path – Der Pfad zur Datei

Diese Parameter ermöglichen es Ihnen, die richtigen Dateien in Ihrem Projekt präzise zu lokalisieren und abzurufen.


Alle Quelldateien im Projekt auflisten

Listet alle Quelldateien in Ihrem Projekt auf, mit Optionen zum Filtern, Sortieren und Paginieren der Ergebnisse. Dies ist nützlich, wenn Sie Ihre Dateien durchsuchen, ihren Status überprüfen oder bestimmte Dateien basierend auf Tag, Pfad oder Upload-Methode finden möchten.

HTTP-Request

GET https://app.ptc.wpml.org/api/v1/source_files

Parameter

Parameter Typ Erforderlich Standard Beschreibung
page integer Nein 1 Die Seitenzahl für die Paginierung. Muss größer als 0 sein.
per_page integer Nein 50 Die Anzahl der Elemente pro Seite. Muss größer als 0 sein.
order_by string Nein created_at Das Feld, nach dem sortiert werden soll. Zulässige Werte: id, created_at, updated_at.
sort string Nein desc Die Sortierrichtung. Zulässige Werte: asc, desc.
file_path string Nein – Filtert nach exaktem Dateipfad.
upload_origin string Nein – Filtert danach, wie die Datei hochgeladen wurde. Zulässige Werte umfassen: git, manual, api.

Antworten

Erfolgsantwort

200 OKapplication/json
{
  "source_files": [
    {
      "id": 123,
      "file_path": "locales/en.po",
      "translation_path": "locales/{{lang}}.po",
      "additional_translation_files": ["locales/{{lang}}.mo"],
      "status": "completed",
      "upload_origin": "git",
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T14:20:00.000Z",
      "file_tag": {
        "id": 456,
        "name": "frontend"
      },
      "download_url": "https://app.ptc.wpml.org/api/v1/source_files/download_translations?file_path=locales/en.po&file_tag_name=frontend"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 150,
    "total_pages": 3,
    "has_next_page": true,
    "has_previous_page": false
  }
}
Antwortschema

Quelldatei-Objekt:

Feld Typ Beschreibung
id integer Die eindeutige Kennung für die Quelldatei.
file_path string Der Pfad zur Quelldatei innerhalb des Projekts.
translation_path string Das Muster dafür, wo übersetzte Dateien gespeichert werden sollen.
additional_translation_files array[string] Die Pfade für eventuelle zusätzliche Ausgabedateien.
status string Der aktuelle Verarbeitungsstatus der Quelldatei.
upload_origin string Wie die Datei hochgeladen wurde (git, manual, api).
created_at string Ein ISO-8601-Zeitstempel, der angibt, wann die Quelldatei ursprünglich erstellt wurde.
updated_at string Ein ISO-8601-Zeitstempel, der angibt, wann die Quelldatei zuletzt aktualisiert wurde.
file_tag object Informationen über das Datei-Tag.
file_tag.id integer Die Kennung des Datei-Tags.
file_tag.name string Der Name des Datei-Tags.
download_url string Die URL zum Herunterladen von Übersetzungen für diese Quelldatei.

Paginierungs-Objekt:

Feld Typ Beschreibung
page integer Die aktuelle Seitenzahl.
per_page integer Die Anzahl der Elemente pro Seite.
total integer Die Gesamtzahl der Quelldateien.
total_pages integer Die Gesamtzahl der Seiten.
has_next_page boolean Gibt an, ob eine nächste Seite verfügbar ist.
has_previous_page boolean Gibt an, ob eine vorherige Seite verfügbar ist.

Fehlerantworten

Nicht autorisiert
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Verboten
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}
Ungültige Parameter
422 Unprocessable Entity
{
  "error": "Invalid parameters provided."
}

Beispiel-Requests

Einfacher Request:

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Gefilterter Request:

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files?file_tag_name=frontend&page=1&per_page=25&order_by=updated_at&sort=desc" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Code-Beispiele

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files?file_tag_name=frontend&page=1&per_page=25" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Übersetzungsstrings abrufen

Ruft alle übersetzbaren Strings aus einer bestimmten Quelldatei ab, zusammen mit ihren vorhandenen Übersetzungen in allen Zielsprachen.

Dieser Endpunkt ist nützlich, um Inhalte abzurufen, die übersetzt werden müssen oder bereits übersetzt wurden. Die Quelldatei wird durch file_path und file_tag_name identifiziert.

HTTP-Request

GET https://app.ptc.wpml.org/api/v1/source_files/translation_strings

Parameter

Parameter Typ Erforderlich Standard Beschreibung
file_path string Ja – Der Pfad zur Quelldatei innerhalb des Projekts.
file_tag_name string Nein – Der Name des Datei-Tags. Wenn nicht angegeben, wird das Standard-Tag des Projekts verwendet.
page integer Nein 1 Die Seitenzahl für die Paginierung (als Cursor verwendet). Muss größer als 0 sein.
q string Nein – Die Suchanfrage, um Übersetzungsstrings nach ihrem Ausgangstext zu filtern.

Antworten

Erfolgsantwort

200 OKapplication/json
{
  "total_strings_count": 1250,
  "translation_strings": [
    {
      "source": "Welcome to our application",
      "translations": {
        "es": "Bienvenido a nuestra aplicación",
        "fr": "Bienvenue dans notre application",
        "de": "Willkommen in unserer Anwendung"
      }
    },
    {
      "source": "Login",
      "translations": {
        "es": "Iniciar sesión",
        "fr": "Connexion",
        "de": "Anmelden"
      }
    }
  ],
  "cursor": 1
}
Antwortschema
Feld Typ Beschreibung
total_strings_count integer Die Gesamtzahl der übersetzbaren Strings in der Quelldatei.
translation_strings array[object] Das Array der Übersetzungsstring-Objekte (paginiert, max. 500 pro Seite).
translation_strings[].source string Der ursprüngliche Ausgangstext, der übersetzt werden soll.
translation_strings[].translations object Ein Hash von Übersetzungen, bei dem die Schlüssel die ISO-Sprachcodes und die Werte die übersetzten Texte sind.
cursor integer Der aktuelle Seiten-Cursor, der für die Paginierung verwendet wird.

Fehlerantworten

Quelldatei nicht gefunden
404 Not Found
{
  "error": "Source file not found"
}
Nicht autorisiert
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Verboten
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}
Ungültige Parameter
422 Unprocessable Entity
{
  "error": "Invalid parameters provided."
}

Beispiel-Requests

Einfacher Request:

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/translation_strings?file_path=locales/en.po" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Ein Request mit Datei-Tag:

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/translation_strings?file_path=locales/en.po&file_tag_name=frontend" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Ein Request mit Paginierung und Suche:

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/translation_strings?file_path=locales/en.po&file_tag_name=frontend&page=2&q=welcome" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Code-Beispiele

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/translation_strings?file_path=locales/en.po&file_tag_name=frontend&page=1&q=login" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Quelldatei erstellen

Registriert eine neue Quelldatei in Ihrem Projekt, sodass sie übersetzungsbereit ist.

Dieser Endpunkt erstellt den Dateieintrag und richtet dessen Übersetzungskonfiguration ein, hängt aber nicht den eigentlichen Dateiinhalt an.

Nach dem Erstellen der Datei müssen Sie den Endpunkt Quelldatei verarbeiten verwenden, um den Inhalt hochzuladen und den Übersetzungsprozess zu starten.

HTTP-Request

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

Parameter

Parameter Typ Erforderlich Beschreibung
file_path string Ja Der Pfad, unter dem die Quelldatei im Projekt gespeichert werden soll. Muss eine unterstützte Dateiendung haben.
output_file_path string Ja Das Ausgabepfad-Muster für übersetzte Dateien. Verwenden Sie {{lang}} als Platzhalter für den Sprachcode.
file_tag_name string Nein Der Name des Datei-Tags, unter dem die Quelldatei registriert werden soll. Wenn nicht angegeben, wird das Standard-Datei-Tag des Projekts verwendet.
translations array[object] Nein Die bereits vorhandenen Übersetzungen, die zusammen mit der Quelldatei hochgeladen werden sollen. Diese Dateien werden wie bereitgestellt gespeichert, und ihre Strings werden von der PTC nicht erneut übersetzt. Beachten Sie, dass die Bereitstellung bestehender Übersetzungen nicht empfohlen wird, da die PTC bessere Ergebnisse liefert, wenn sie den vollständigen Kontext Ihres Projekts nutzen und von Grund auf übersetzen kann.
translations[].target_language_iso string Ja Der ISO-Code der Zielsprache für diese Übersetzung. Sie finden die vollständige Liste der unterstützten Sprachen und ihrer ISO-Codes im Endpunkt Alle Zielsprachen auflisten.
translations[].file file Ja Die Übersetzungsdatei, die hochgeladen werden soll.
additional_translation_files array[object] Nein Konfigurationen für zusätzliche Ausgabedateien für bestimmte Formate. Um zu sehen, welche Formate zusätzliche Ausgabedateien unterstützen, lesen Sie die Dokumentation zum Endpunkt Unterstützte Dateiformate auflisten. Bei nicht unterstützten Formaten wird dieses Feld ignoriert.
additional_translation_files[].type string Ja Weitere Details finden Sie unter unterstützte Dateiformate.
additional_translation_files[].path string Ja Das Pfadmuster für die Datei.

Antworten

Erfolgsantwort

201 Createdapplication/json
{
  "source_file": {
    "id": 123,
    "file_path": "src/locales/en.json",
    "created_at": "2024-01-15T10:30:00.000Z",
    "file_tag": {
      "id": 456,
      "name": "frontend"
    }
  }
}
Antwortschema
Feld Typ Beschreibung
source_file.id integer Die eindeutige Kennung für die erstellte Quelldatei.
source_file.file_path string Der Pfad der Quelldatei innerhalb des Projekts.
source_file.created_at string Ein ISO-8601-Zeitstempel, der angibt, wann die Quelldatei ursprünglich erstellt wurde.
source_file.file_tag.id integer Die Kennung des Datei-Tags.
source_file.file_tag.name string Der Name des Datei-Tags.

Fehlerantworten

Validierung fehlgeschlagen
422 Unprocessable Entity
{
  "success": false,
  "error": "Source file creation failed"
}
Nicht autorisiert
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Verboten
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

Beispiel-Requests

Einfache Erstellung einer Quelldatei:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file_path=src/locales/en.json" \
  -F "output_file_path=src/locales/{{lang}}.json" \
  -F "file_tag_name=frontend"

Das Erstellen akzeptiert keine callback_url. Die Registrierung einer Quelldatei startet keine Übersetzung, daher gibt es nichts, was ein Callback ankündigen könnte — übergeben Sie sie stattdessen an Quelldatei verarbeiten oder an Quelldateien im Stapel hochladen, da dies die Aufrufe sind, die die Arbeit beginnen.

Request mit bereits vorhandenen Übersetzungen:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file_path=src/messages.json" \
  -F "output_file_path=locales/{{lang}}/messages.json" \
  -F "translations[0][target_language_iso]=es" \
  -F "translations[0][file]=@spanish_translations.json" \
  -F "translations[1][target_language_iso]=fr" \
  -F "translations[1][file]=@french_translations.json"

Request mit zusätzlichen Ausgabedateien:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file_path=src/messages.po" \
  -F "output_file_path=locales/{{lang}}/messages.po" \
  -F "additional_translation_files[][type]=mo" \
  -F "additional_translation_files[][path]=locales/{{lang}}/messages.mo" \
  -F "additional_translation_files[][type]=json" \
  -F "additional_translation_files[][path]=locales/{{lang}}/messages.json"

Code-Beispiele

  • JavaScript (FormData)
  • Python (requests)
  • PHP (cURL)
  • Node.js (axios)
  • Callback-Request-Body
curl -X POST "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file_path=src/locales/en.json" \
  -F "output_file_path=src/locales/{{lang}}.json"
{
  "source_file_id": 123,
  "status": "completed",
  "file_tag_name": "frontend",
  "download_url": "https://app.ptc.wpml.org/api/v1/source_files/download_translations?file_path=src/locales/en.json&file_tag_name=frontend",
  "file_path": "src/locales/en.json"
}

Quelldatei verarbeiten

Lädt Inhalte in eine bestehende Quelldatei hoch und startet den Übersetzungsprozess.

Dieser Endpunkt ersetzt den aktuellen Inhalt der Datei, aktualisiert die gespeicherten übersetzbaren Strings und startet die automatische Übersetzung.

Um diesen Endpunkt zu verwenden, muss die Quelldatei bereits im Projekt existieren. Wenn Sie sie noch nicht erstellt haben, siehe Quelldatei erstellen.

HTTP-Request

PUT https://app.ptc.wpml.org/api/v1/source_files/process

Parameter

Parameter Typ Erforderlich Beschreibung
file file Ja Die Quelldatei, die hochgeladen werden soll. Der Dateiinhalt wird validiert, um sicherzustellen, dass er mit der deklarierten Dateiendung übereinstimmt. Wenn die Dateiendung beispielsweise .json lautet, muss der hochgeladene Inhalt gültiges JSON sein.
file_path string Ja Der Pfad zur bestehenden Quelldatei im Projekt, die aktualisiert werden soll.
file_tag_name string Nein Der Name des Datei-Tags, das mit der Quelldatei verknüpft ist. Wenn nicht angegeben, wird das Standard-Datei-Tag des Projekts verwendet.
callback_url string Nein Die URL, die Webhook-Benachrichtigungen empfängt, wenn die Dateiverarbeitung abgeschlossen ist.

Antworten

Erfolgsantwort

200 OKapplication/json
{
  "source_file": {
    "id": 123,
    "file_path": "src/locales/en.json",
    "created_at": "2024-01-15T10:30:00.000Z",
    "file_tag": {
      "id": 456,
      "name": "frontend"
    }
  }
}
Antwortschema
Feld Typ Beschreibung
source_file.id integer Die eindeutige Kennung für die verarbeitete Quelldatei.
source_file.file_path string Der Pfad der Quelldatei innerhalb des Projekts.
source_file.created_at string Ein ISO-8601-Zeitstempel, der angibt, wann die Quelldatei ursprünglich erstellt wurde.
source_file.file_tag.id integer Die Kennung des Datei-Tags.
source_file.file_tag.name string Der Name des Datei-Tags.

Fehlerantworten

Nicht unterstütztes oder ungültiges Dateiformat

Die Verarbeitung ersetzt den Inhalt der Datei durch das, was Sie hochladen, sodass es kein Suchen gibt, das fehlschlagen könnte — dieser Endpunkt hat keinen Not-Found-Fall. Die einzige Ablehnung, die er zurückgibt, ist die Inhaltsprüfung der hochgeladenen Datei.

422 Unprocessable Entity
{
  "success": false,
  "message": "Unprocessable Entity",
  "code": 422,
  "errors": [9001]
}

errors ist ein Array numerischer Codes, kein nach Feldern geschlüsseltes Objekt. 9001 bedeutet, dass der Inhalt nicht als das Format geparst werden konnte, das seine Dateiendung angibt. Einige Ablehnungen fügen daneben ein additional_info-Objekt mit den genauen Angaben hinzu.

Nicht autorisiert
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Verboten
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

Workflow

  1. Voraussetzung: Die Quelldatei muss bereits über Quelldatei erstellen erstellt worden sein.
  2. Datei-Upload: Neuer Inhalt wird hochgeladen und ersetzt den bestehenden Dateiinhalt.
  3. Verarbeitung: Die neuen übersetzbaren Strings werden extrahiert und automatisch übersetzt.
  4. Callback: Eine optionale Webhook-Benachrichtigung wird gesendet, wenn die Verarbeitung abgeschlossen ist.

Webhook-Callback

Wenn eine callback_url angegeben wird, sendet die PTC einen POST-Request an diese URL, wenn die Verarbeitung abgeschlossen ist.

Callback-Request-Body:

{
  "source_file_id": 123,
  "status": "completed",
  "file_tag_name": "frontend",
  "download_url": "https://app.ptc.wpml.org/api/v1/source_files/download_translations?file_path=src/locales/en.json&file_tag_name=frontend",
  "file_path": "src/locales/en.json"
}

Beispiel-Requests

Einfache Dateiverarbeitung:

curl -X PUT "https://app.ptc.wpml.org/api/v1/source_files/process" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@updated_translations.json" \
  -F "file_path=src/locales/en.json" \
  -F "file_tag_name=frontend"

Request mit Callback-URL:

curl -X PUT "https://app.ptc.wpml.org/api/v1/source_files/process" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@messages.po" \
  -F "file_path=locales/messages.po" \
  -F "callback_url=https://your-app.com/webhooks/translation-complete"

Code-Beispiele

curl -X PUT "https://app.ptc.wpml.org/api/v1/source_files/process" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@updated_translations.json" \
  -F "file_path=src/locales/en.json" \
  -F "file_tag_name=frontend" \
  -F "callback_url=https://your-app.com/webhooks/complete"

Unterstützte Dateiformate

Der Endpunkt unterstützt verschiedene übersetzbare Dateiformate, darunter unter anderem JSON-, PO/POT-, XLIFF- und Properties-Dateien. Die Validierung des Dateiformats erfolgt während des Uploads, um die Kompatibilität sicherzustellen.

Verwenden Sie den Endpunkt Unterstützte Dateiformate auflisten, um die vollständige Liste der unterstützten Formate zu erhalten.


Übersetzungsstatus abrufen

Ruft den aktuellen Übersetzungsfortschritt für eine bestimmte Quelldatei ab, einschließlich der Angabe, wie viel abgeschlossen ist, und ihres gesamten Verarbeitungsstatus.

Dies ist nützlich für:

  • Fortschrittsüberwachung – Verfolgung des Übersetzungsfortschritts bei lang laufenden Jobs
  • UI-Updates – Anzeige von Abschluss-Prozentsätzen in Ihrer Anwendung
  • Workflow-Integration – Auslösen von Aktionen, wenn die Übersetzung einen definierten Schwellenwert erreicht

HTTP-Request

GET https://app.ptc.wpml.org/api/v1/source_files/translation_status

Parameter

Parameter Typ Erforderlich Beschreibung
file_path string Ja Der Pfad zur Quelldatei innerhalb des Projekts.
file_tag_name string Nein Der Name des Datei-Tags. Wenn nicht angegeben, wird das Standard-Datei-Tag des Projekts verwendet.

Antworten

Erfolgsantwort

200 OKapplication/json
{
  "translation_status": {
    "status": "completed",
    "completeness": 100
  }
}
Antwortschema
Feld Typ Beschreibung
translation_status.status string Der aktuelle Verarbeitungsstatus der Quelldatei. Siehe Statuswerte unten.
translation_status.completeness number Der Prozentsatz der übersetzten Strings (0–100). Berechnet als (completed_translatable_strings / total_translatable_strings) × 100.

Statuswerte

Das Feld status kann die folgenden Werte enthalten:

Status Beschreibung
pending Die Quelldatei wartet auf die Verarbeitung.
processing Die Übersetzung ist derzeit im Gange.
completed Alle Übersetzungen wurden abgeschlossen.
failed Der Übersetzungsprozess stieß auf Fehler.

Fehlerantworten

Quelldatei nicht gefunden
404 Not Found
{
  "error": "Source file not found"
}
Nicht autorisiert
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Verboten
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}
Ungültige Parameter
422 Unprocessable Entity
{
  "error": "Invalid parameters provided."
}

Beispiel-Requests

Einfacher Request:

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/translation_status?file_path=locales/en.po" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Request mit Datei-Tag:

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/translation_status?file_path=locales/en.po&file_tag_name=frontend" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Code-Beispiele

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/translation_status?file_path=locales/en.po&file_tag_name=frontend" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Alle Übersetzungen herunterladen

Lädt alle übersetzten Dateien für eine bestimmte Quelldatei als ZIP-Archiv herunter.

Dieser Endpunkt erstellt und liefert ein komprimiertes Archiv, das alle Übersetzungsdateien in den Zielsprachen für die angegebene Quelldatei enthält.

Wenn für die Datei keine Übersetzungen verfügbar sind, gibt der Request einen Fehler 404 Not Found zurück.

HTTP-Request

GET https://app.ptc.wpml.org/api/v1/source_files/download_translations

Parameter

Parameter Typ Erforderlich Beschreibung
file_path string Ja Der Pfad zur Quelldatei innerhalb des Projekts.
file_tag_name string Nein Der Name des Datei-Tags. Wenn nicht angegeben, wird das Standard-Datei-Tag des Projekts verwendet. Eine Quelldatei wird eindeutig durch die Kombination von file_path und file_tag_name identifiziert.

Antworten

Erfolgsantwort

200 OKapplication/zip202 AcceptedRetry-After: 30
{
  "status": "processing",
  "message": "Translations are still in progress. Please retry after the specified delay.",
  "retry_after": 30
}

Die PTC verarbeitet Übersetzungen asynchron. Normalerweise gibt es eine kurze Wartezeit zwischen dem Hochladen einer Quelldatei und der Verfügbarkeit der Übersetzungen zum Herunterladen.

Wenn dies geschieht, warten Sie die in Retry-After angegebene Anzahl von Sekunden.

Fehlerantworten

Quelldatei nicht gefunden
404 Not Found
{
  "error": "Source file not found"
}
Keine Übersetzungen verfügbar
404 Not Found
{
  "error": "No translations are available for this source file"
}
Nicht autorisiert
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Verboten
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}
Ungültige Parameter
422 Unprocessable Entity
{
  "error": "Invalid parameters provided."
}

Beispiel-Requests

Einfacher Request:

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/download_translations?file_path=locales/en.po" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -o translations.zip

Request mit Datei-Tag:

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/download_translations?file_path=locales/en.po&file_tag_name=frontend" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -o frontend-translations.zip

Code-Beispiele

curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/download_translations?file_path=locales/en.po&file_tag_name=frontend" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -o translations.zip
# 200 -> saves the zip; 202 -> {"status":"processing","retry_after":N} (retry later);
# 404 -> {"error":"No translations are available for this source file"}

Quelldateien im Stapel hochladen

Lädt ein ZIP-Archiv hoch, das mehrere übersetzbare Dateien enthält. Jede Datei im Archiv wird extrahiert, validiert und verarbeitet. Unterstützte Formate werden automatisch identifiziert.

Dies ist die Batch-Version von Quelldatei verarbeiten, die entwickelt wurde, um groß angelegte Aktualisierungen zu beschleunigen.

Zusätzliche Informationen

  • Wenn eine Datei mit einer bestehenden Quelldatei übereinstimmt, wird sie mit dem neuen Inhalt aktualisiert und die Übersetzungen werden erneut ausgelöst.
  • Wenn eine Datei unterstützt wird, aber mit keiner bestehenden Quelldatei übereinstimmt, wird sie zur Liste not_found_files hinzugefügt und ignoriert.
  • Dateien mit nicht unterstützten Formaten werden unter unsupported_files aufgelistet und ignoriert.
  • Dateien mit ungültigem Inhalt werden ebenfalls unter unsupported_files aufgelistet und ignoriert.
  • Die Verarbeitung großer Archive kann länger dauern. Dateien werden nacheinander verarbeitet, um Systemressourcen zu schonen. Daher ist es am besten, sehr große Uploads (mehr als 100 Dateien) in kleinere Batches aufzuteilen. Alle Dateien im Archiv werden auf automatische Übersetzung eingestellt.
  • Die hochgeladene ZIP-Datei muss gültig und lesbar sein. Alle darin enthaltenen Dateien müssen in einem unterstützten Format vorliegen. Dateinamen sollten keine Sonderzeichen enthalten, die zu Pfadproblemen führen könnten.
  • Wenn eine callback_url angegeben wird, wird für jede verarbeitete Quelldatei ein POST-Request mit den Ergebnissen gesendet.

HTTP-Request

POST https://app.ptc.wpml.org/api/v1/source_files/bulk

Parameter

Parameter Typ Erforderlich Beschreibung
zip_file file Ja Ein ZIP-Archiv, das die hochzuladenden Quelldateien enthält. Es muss eine gültige ZIP-Datei sein.
file_tag_name string Nein Der Name des Datei-Tags, das mit allen Quelldateien im Archiv verknüpft werden soll. Wenn nicht angegeben, wird das Standard-Datei-Tag des Projekts verwendet. Jede Quelldatei wird eindeutig durch die Kombination aus file_path und file_tag_name identifiziert.
callback_url string Nein Die URL, die Webhook-Benachrichtigungen empfängt, wenn jede Datei verarbeitet ist.

Erwartete Struktur der ZIP-Datei

Die ZIP-Datei kann Quelldateien in einer beliebigen Verzeichnisstruktur enthalten. Die Verzeichnisstruktur bleibt erhalten, und Dateien werden rekursiv verarbeitet.

Beispielhafte ZIP-Struktur:

source-files.zip
├── locales/
│   ├── messages-en.po
│   ├── validation-en.po
│   └── admin-en.po
├── frontend/
│   ├── components-en.json
│   └── pages-en.json
│   └── not-found-en.json
├── app-strings-en.properties
└── readme.txt (will be ignored)

Unterstützte Dateitypen:

  • JSON: .json-Dateien
  • Gettext: .po-, .pot-Dateien
  • Properties: .properties-Dateien
  • YAML: .yml-, .yaml-Dateien
  • XML: .xml-Dateien
  • Strings: .strings-Dateien
  • XLIFF: .xliff-, .xlf-Dateien
  • CSV: .csv-Dateien
  • PHP: .php-Dateien

Antworten

Erfolgsantwort

200 OKapplication/json
{
  "success": true,
  "file_tag": {
      "id": 456,
      "name": "backend"
  },
  "processed_files": [
    {
      "id": 123,
      "file_path": "locales/messages-en.po",
      "created_at": "2024-01-15T10:30:00.000Z",
      "file_tag": {
        "id": 456,
        "name": "backend"
      }
    },
    {
      "id": 124,
      "file_path": "locales/validation-en.po",
      "created_at": "2024-01-15T10:30:05.000Z",
      "file_tag": {
        "id": 456,
        "name": "backend"
      }
    }
  ],
  "unsupported_files": [
    "readme.txt",
    "config.ini"
  ],
  "not_found_files": ["frontend/not-found-en.json"]
}
Antwortschema
Feld Typ Beschreibung
success boolean Gibt an, ob der Bulk-Upload-Vorgang erfolgreich war.
file_tag object Die Informationen zum Datei-Tag.
file_tag.id integer Die Kennung des Datei-Tags.
file_tag.name string Der Name des Datei-Tags.
processed_files array[object] Ein Array von Quelldateien, die erfolgreich verarbeitet wurden.
processed_files[].id integer Die eindeutige Kennung für die erstellte Quelldatei.
processed_files[].file_path string Der Pfad der Quelldatei, wobei die ursprüngliche ZIP-Struktur beibehalten wird.
processed_files[].created_at string Ein ISO-8601-Zeitstempel, der angibt, wann die Quelldatei erstellt wurde.
processed_files[].file_tag object Die Informationen zum Datei-Tag.
processed_files[].file_tag.id integer Die Kennung des Datei-Tags.
processed_files[].file_tag.name string Der Name des Datei-Tags.
unsupported_files array[string] Ein Array von Dateinamen, die nicht in einem unterstützten Format vorliegen.
not_found_files array[string] Ein Array von unterstützten Dateien, die mit keiner bestehenden Quelldatei übereinstimmten und ignoriert wurden.

Fehlerantworten

Ungültige ZIP-Datei

422 Unprocessable Entity
{
  "success": false,
  "error": "File format is invalid",
  "processed_files": [],
  "unsupported_files": []
}

Verarbeitung fehlgeschlagen

422 Unprocessable Entity
{
  "success": false,
  "error": "Failed to process ZIP archive",
  "processed_files": [],
  "unsupported_files": []
}

Nicht autorisiert

401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}

Verboten

403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

Webhook-Callback

Wenn eine callback_url angegeben wird, wird für jede verarbeitete Datei ein POST-Request gesendet.

Callback-Request-Body (pro Datei):

{
  "source_file_id": 123,
  "status": "completed",
  "file_tag_name": "backend",
  "download_url": "https://app.ptc.wpml.org/api/v1/source_files/download_translations?file_path=locales/messages-en.po&file_tag_name=backend",
  "file_path": "locales/messages-en.po"
}

Beispiel-Requests

Einfacher Bulk-Upload:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files/bulk" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "zip_file=@source-files.zip" \
  -F "file_tag_name=backend"

Request mit Callback-URL:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files/bulk" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "zip_file=@translations.zip" \
  -F "file_tag_name=localization" \
  -F "callback_url=https://your-app.com/webhooks/bulk-complete"

Code-Beispiele

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files/bulk" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "zip_file=@source-files.zip" \
  -F "file_tag_name=backend" \
  -F "callback_url=https://your-app.com/webhooks/complete"
Weiter:

Unterstützte Dateiformate und Zielsprachen über die API finden →