Quelldateien über die API hochladen und verwalten

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

Ob Sie eine einzelne Datei verwalten oder einen kontinuierlichen Lokalisierungs-Workflow automatisieren, diese API gibt Ihnen die volle Kontrolle über die Inhalte, die Sie zur Übersetzung senden, und 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. Zum Beispiel können Datei-Tags Folgendes anzeigen:

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

Datei-Tag-Namen sind in den meisten API-Operationen optional. Jede Quelldatei hat jedoch immer mindestens ein Tag. Ein Standard-Datei-Tag wird automatisch erstellt und zugewiesen, wenn ein Projekt eingerichtet wird. Dieses Standardverhalten sorgt für Ordnung in Projekten, selbst bei einfachen Setups, und ermöglicht Ihnen gleichzeitig, bei Bedarf komplexere Tagging-Strukturen aufzubauen.

Datei-Tag-Name + Dateipfad

Jede Quelldatei wird eindeutig durch die Kombination aus ihrem Datei-Tag-Namen und ihrem Dateipfad 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 verwandte Endpunkte Abfrageparameter akzeptieren, wie z. B.:

  • file_tag_name – Das Tag, das der Datei zugeordnet ist
  • file_path – Der Pfad zur Datei

Diese Parameter ermöglichen es Ihnen, die richtigen Dateien aus 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 anhand von Tag, Pfad oder Upload-Methode finden möchten.

HTTP-Anfrage

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

Parameter

ParameterTypErforderlichStandardBeschreibung
pageGanzzahlNein1Die Seitenzahl für die Paginierung. Muss größer als 0 sein.
per_pageGanzzahlNein50Die Anzahl der Elemente pro Seite. Muss größer als 0 sein.
order_byZeichenketteNeincreated_atDas Feld, nach dem sortiert werden soll. Zulässige Werte: id, created_at, updated_at.
sortZeichenketteNeindescDie Richtung der Sortierung. Zulässige Werte: asc, desc.
file_pathZeichenketteNeinFiltert nach exaktem Dateipfad.
upload_originZeichenketteNeinFiltert danach, wie die Datei hochgeladen wurde. Zulässige Werte sind: git, manual, api.

Antworten

Erfolgsantwort

  • Code: 200 OK
  • Inhaltstyp: application/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=locale/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:

FeldTypBeschreibung
idGanzzahlDie eindeutige Kennung für die Quelldatei.
file_pathZeichenketteDer Pfad zur Quelldatei innerhalb des Projekts.
translation_pathZeichenketteDas Muster für den Speicherort übersetzter Dateien.
additional_translation_filesarray[string]Die Pfade für alle zusätzlichen Ausgabedateien.
statusZeichenketteDer aktuelle Verarbeitungsstatus der Quelldatei.
upload_originZeichenketteWie die Datei hochgeladen wurde (git, manual, api).
created_atZeichenketteEin ISO 8601-Zeitstempel, der angibt, wann die Quelldatei ursprünglich erstellt wurde.
updated_atZeichenketteEin ISO-8601-Zeitstempel, der angibt, wann die Quelldatei zuletzt aktualisiert wurde.
file_tagobjectInformationen über das Datei-Tag.
file_tag.idGanzzahlDie Dateietikett-Kennung.
file_tag.nameZeichenketteDer Dateietikett-Name.
download_urlZeichenketteDie URL zum Herunterladen von Übersetzungen für diese Quelldatei.

Paginierungsobjekt:

FeldTypBeschreibung
pageGanzzahlDie aktuelle Seitenzahl.
per_pageGanzzahlDie Anzahl der Elemente pro Seite.
totalGanzzahlDie Gesamtzahl der Quelldateien.
total_pagesGanzzahlDie Gesamtzahl der Seiten.
has_next_pagebooleanOb eine nächste Seite verfügbar ist.
has_previous_pagebooleanOb eine vorherige Seite verfügbar ist.

Fehlerantworten

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

Beispielanfragen

Basis-Anfrage:

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

Gefilterte Anfrage:

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 "Content-Type: application/json"

Codebeispiele

const response = await fetch('https://app.ptc.wpml.org/api/v1/source_files?file_tag_name=frontend&page=1&per_page=25', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);
import requests

headers = {
    'Content-Type': 'application/json'
}

params = {
    'file_tag_name': 'frontend',
    'page': 1,
    'per_page': 25
}

response = requests.get('https://app.ptc.wpml.org/api/v1/source_files', 
                       headers=headers, params=params)
data = response.json()
print(data)
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://app.ptc.wpml.org/api/v1/source_files?file_tag_name=frontend&page=1&per_page=25',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json'
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

$data = json_decode($response, true);
print_r($data);
?>
const axios = require('axios');

const response = await axios.get('https://app.ptc.wpml.org/api/v1/source_files', {
  headers: {
    'Content-Type': 'application/json'
  },
  params: {
    file_tag_name: 'frontend',
    page: 1,
    per_page: 25
  }
});

console.log(response.data);

Übersetzungs-Strings abrufen

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

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

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

Parameter

ParameterTypErforderlichStandardBeschreibung
file_pathZeichenketteJaDer Pfad zur Quelldatei innerhalb des Projekts.
file_tag_nameZeichenketteNeinDer Datei-Tag-Name. Wenn nicht angegeben, wird das Standard-Tag des Projekts verwendet.
pageGanzzahlNein1Die Seitenzahl für die Paginierung (als Cursor verwendet). Muss größer als 0 sein.
qZeichenketteNeinDie Suchabfrage zum Filtern von Übersetzungs-Strings nach ihrem Quelltext.

Antworten

Erfolgsantwort

  • Code: 200 OK
  • Inhaltstyp: application/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
FeldTypBeschreibung
total_strings_countGanzzahlDie Gesamtzahl der übersetzbaren Strings in der Quelldatei.
translation_stringsarray[object]Das Array von Übersetzung-String-Objekten (paginiert, max. 500 pro Seite).
translation_strings[].sourceZeichenketteDer ursprüngliche Quelltext, der übersetzt werden soll.
translation_strings[].translationsobjectEin Hash von Übersetzungen, wobei die Schlüssel Sprach-ISO-Codes und die Werte der übersetzte Text sind.
cursorGanzzahlDer aktuelle Seiten-Cursor, der für die Paginierung verwendet wird.

Fehlerantworten

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

Beispielanfragen

Basis-Anfrage:

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

Eine Anfrage 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 "Content-Type: application/json"

Eine Anfrage 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 "Content-Type: application/json"

Codebeispiele

const response = await fetch('https://app.ptc.wpml.org/api/v1/source_files/translation_strings?file_path=locales/en.po&file_tag_name=frontend&page=1&q=login', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);

import requests

headers = {
    'Content-Type': 'application/json'
}

params = {
    'file_path': 'locales/en.po',
    'file_tag_name': 'frontend',
    'page': 1,
    'q': 'login'
}

response = requests.get('https://app.ptc.wpml.org/api/v1/source_files/translation_strings', 
                       headers=headers, params=params)
data = response.json()
print(data)
<?php
$params = http_build_query([
    'file_path' => 'locales/en.po',
    'file_tag_name' => 'frontend',
    'page' => 1,
    'q' => 'login'
]);

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://app.ptc.wpml.org/api/v1/source_files/translation_strings?{$params}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json'
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

$data = json_decode($response, true);
print_r($data);
?>

const axios = require('axios');

const response = await axios.get('https://app.ptc.wpml.org/api/v1/source_files/translation_strings', {
  headers: {
    'Content-Type': 'application/json'
  },
  params: {
    file_path: 'locales/en.po',
    file_tag_name: 'frontend',
    page: 1,
    q: 'login'
  }
});

console.log(response.data);


Die Quelldatei erstellen

Registriert eine neue Quelldatei in Ihrem Projekt, damit sie zur Übersetzung bereitsteht.

Dieser Endpunkt erstellt den Dateieintrag und richtet dessen Übersetzungskonfiguration ein, fügt aber nicht den tatsächlichen 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-Anfrage

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

Parameter

ParameterTypErforderlichBeschreibung
file_pathZeichenketteJaDer Pfad, in dem die Quelldatei im Projekt gespeichert werden soll. Muss eine unterstützte Erweiterung haben.
output_file_pathZeichenketteJaDas Ausgabepfadmuster für übersetzte Dateien. Verwenden Sie {{lang}} als Placeholder für den Sprachcode.
translationsarray[object]NeinDie bereits vorhandenen Übersetzungsdateien, die zusammen mit der Quelldatei hochgeladen werden sollen. Diese Dateien werden wie angegeben gespeichert, und ihre Strings werden von PTC nicht erneut übersetzt.
Beachten Sie, dass das Bereitstellen vorhandener Übersetzungen nicht empfohlen wird, da PTC bessere Ergebnisse erzielt, wenn es den vollständigen Kontext Ihres Projekts verwenden und von Grund auf neu übersetzen kann.
translations[].target_language_isoZeichenketteJaDer ISO-Code der Zielsprache für diese Übersetzung. Die vollständige Liste der unterstützten Sprachen und ihrer ISO-Codes finden Sie im Endpunkt Alle Zielsprachen auflisten.
translations[].fileDateiJaDie hochzuladende Übersetzungsdatei.
additional_translation_filesarray[object]NeinZusätzliche Ausgabedateikonfigurationen für bestimmte Formate.
Um zu sehen, welche Formate zusätzliche Ausgabedateien unterstützen, lesen Sie den Endpunkt Unterstützte Dateiformate auflisten. Für nicht unterstützte Formate wird dieses Feld ignoriert.
additional_translation_files[].typeZeichenketteJaWeitere Informationen finden Sie unter unterstützte Dateiformate.
additional_translation_files[].pathZeichenketteJaDas Pfadmuster für die Datei.

Antworten

Erfolgsantwort

  • Code: 201 Created
  • Inhaltstyp: application/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
FeldTypBeschreibung
source_file.idGanzzahlDie eindeutige Kennung für die erstellte Quelldatei.
source_file.file_pathZeichenketteDer Pfad der Quelldatei innerhalb des Projekts.
source_file.created_atZeichenketteEin ISO 8601-Zeitstempel, der angibt, wann die Quelldatei ursprünglich erstellt wurde.
source_file.file_tag.idGanzzahlDie Dateietikett-Kennung.
source_file.file_tag.nameZeichenketteDer Dateietikett-Name.

Fehlerantworten

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

Beispielanfragen

Einfache Erstellung einer Quelldatei:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Content-Type: multipart/form-data" \
  -F "file_path=src/locales/en.json" \
  -F "output_file_path=src/locales/{lang}.json" \
  -F "file_tag_name=frontend"

Anfrage mit Callback-URL:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Content-Type: multipart/form-data" \
  -F "file_path=src/locales/messages.po" \
  -F "output_file_path=locales/{lang}/messages.po" \
  -F "callback_url=https://your-app.com/webhooks/translation-complete"

Anfrage mit bereits vorhandenen Übersetzungen:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Content-Type: multipart/form-data" \
  -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"

Anfrage mit zusätzlichen Ausgabedateien:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Content-Type: multipart/form-data" \
  -F "file_path=src/messages.po" \
  -F "output_file_path=locales/{lang}/messages.po" \
  -F "additional_translation_files[mo]=locales/{lang}/messages.mo" \
  -F "additional_translation_files[json]=locales/{lang}/messages.json"

Codebeispiele

const formData = new FormData();
formData.append('file_path', 'src/locales/en.json');
formData.append('output_file_path', 'src/locales/{lang}.json');
formData.append('file_tag_name', 'frontend');
formData.append('callback_url', 'https://your-app.com/webhooks/complete');

const response = await fetch('https://app.ptc.wpml.org/api/v1/source_files', {
  method: 'POST',
  body: formData
});

const data = await response.json();
console.log(data);


import requests

data = {
    'file_path': 'src/locales/en.json',
    'output_file_path': 'src/locales/{lang}.json',
    'file_tag_name': 'frontend',
    'callback_url': 'https://your-app.com/webhooks/complete'
}

response = requests.post('https://app.ptc.wpml.org/api/v1/source_files', data=data)
result = response.json()
print(result)

<?php
$data = [
    'file_path' => 'src/locales/en.json',
    'output_file_path' => 'src/locales/{lang}.json',
    'file_tag_name' => 'frontend',
    'callback_url' => 'https://your-app.com/webhooks/complete'
];

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => 'https://app.ptc.wpml.org/api/v1/source_files',
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $data,
    CURLOPT_RETURNTRANSFER => true,
]);

$response = curl_exec($curl);
curl_close($curl);

$result = json_decode($response, true);
print_r($result);
?>

const axios = require('axios');
const FormData = require('form-data');

const formData = new FormData();
formData.append('file_path', 'src/locales/en.json');
formData.append('output_file_path', 'src/locales/{lang}.json');
formData.append('file_tag_name', 'frontend');
formData.append('callback_url', 'https://your-app.com/webhooks/complete');

const response = await axios.post('https://app.ptc.wpml.org/api/v1/source_files', formData, {
  headers: formData.getHeaders()
});

console.log(response.data);


{
  "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 Zeichenketten und startet die automatische Übersetzung.

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

HTTP-Anfrage

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

Parameter

ParameterTypErforderlichBeschreibung
fileDateiJaDie hochzuladende Quelldatei. Der Dateiinhalt wird validiert, um sicherzustellen, dass er mit der deklarierten Erweiterung übereinstimmt. Wenn die Dateierweiterung beispielsweise .json ist, muss der hochgeladene Inhalt gültiges JSON sein.
file_pathZeichenketteJaDer Pfad zur vorhandenen Quelldatei im Projekt, die aktualisiert werden soll.
file_tag_nameZeichenketteNeinDer Name des Dateietiketts, das der Quelldatei zugeordnet ist. Wenn kein Dateietikett angegeben wird, wird das Standard-Dateietikett des Projekts verwendet.
callback_urlZeichenketteNeinDie URL, die Webhook-Benachrichtigungen empfängt, wenn die Dateiverarbeitung abgeschlossen ist.

Antworten

Erfolgsantwort

  • Code: 200 OK
  • Inhaltstyp: application/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
FeldTypBeschreibung
source_file.idGanzzahlDie eindeutige Kennung für die verarbeitete Quelldatei.
source_file.file_pathZeichenketteDer Pfad der Quelldatei innerhalb des Projekts.
source_file.created_atZeichenketteEin ISO 8601-Zeitstempel, der angibt, wann die Quelldatei ursprünglich erstellt wurde.
source_file.file_tag.idGanzzahlDie Dateietikett-Kennung.
source_file.file_tag.nameZeichenketteDer Dateietikett-Name.

Fehlerantworten

Quelldatei nicht gefunden
  • Code: 422 Unprocessable Entity
{
  "errors": {
    "file": ["File format is invalid or not supported"]
  }
}
Nicht autorisiert
  • Code: 401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Verboten
  • Code: 403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

Workflow

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

Webhook-Callback

Wenn ein callback_url bereitgestellt wird, sendet PTC eine POST-Anfrage an diese URL, wenn die Verarbeitung abgeschlossen ist.

Callback-Anfragetext:

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

Beispielanfragen

Grundlegende Dateiverarbeitung:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files/process" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@updated_translations.json" \
  -F "file_path=src/locales/en.json" \
  -F "file_tag_name=frontend"

Anfrage mit Callback-URL:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files/process" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@messages.po" \
  -F "file_path=locales/messages.po" \
  -F "callback_url=https://your-app.com/webhooks/translation-complete"

Codebeispiele

const formData = new FormData();
const fileInput = document.getElementById('file-input');
formData.append('file', fileInput.files[0]);
formData.append('file_path', 'src/locales/en.json');
formData.append('file_tag_name', 'frontend');
formData.append('callback_url', 'https://your-app.com/webhooks/complete');

const response = await fetch('https://app.ptc.wpml.org/api/v1/source_files/process', {
  method: 'POST',
  body: formData
});

const data = await response.json();
console.log(data);

import requests

files = {'file': open('updated_translations.json', 'rb')}
data = {
    'file_path': 'src/locales/en.json',
    'file_tag_name': 'frontend',
    'callback_url': 'https://your-app.com/webhooks/complete'
}

response = requests.post('https://app.ptc.wpml.org/api/v1/source_files/process', 
                        files=files, data=data)
result = response.json()
print(result)
<?php
$file_path = 'updated_translations.json';
$post_data = [
    'file' => new CURLFile($file_path),
    'file_path' => 'src/locales/en.json',
    'file_tag_name' => 'frontend',
    'callback_url' => 'https://your-app.com/webhooks/complete'
];

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => 'https://app.ptc.wpml.org/api/v1/source_files/process',
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $post_data,
    CURLOPT_RETURNTRANSFER => true,
]);

$response = curl_exec($curl);
curl_close($curl);

$result = json_decode($response, true);
print_r($result);
?>


const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

const formData = new FormData();
formData.append('file', fs.createReadStream('updated_translations.json'));
formData.append('file_path', 'src/locales/en.json');
formData.append('file_tag_name', 'frontend');
formData.append('callback_url', 'https://your-app.com/webhooks/complete');

const response = await axios.post('https://app.ptc.wpml.org/api/v1/source_files/process', formData, {
  headers: formData.getHeaders()
});

console.log(response.data);

Unterstützte Dateiformate

Der Endpunkt unterstützt verschiedene übersetzbare Dateiformate, darunter JSON, PO/POT, XLIFF und Properties-Dateien, neben anderen.
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 des Fertigstellungsgrades und des gesamten Verarbeitungsstatus.

Dies ist nützlich für:

  • Fortschrittsüberwachung – Verfolgung des Übersetzungsfortschritts für langwierige Aufträge
  • UI-Aktualisierungen – Anzeige von Fertigstellungsprozentsätzen in Ihrer Anwendung
  • Workflow-Integration – Auslösen von Aktionen, wenn die Übersetzung einen definierten Schwellenwert erreicht

HTTP-Anfrage

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

Parameter

ParameterTypErforderlichBeschreibung
file_pathZeichenketteJaDer Pfad zur Quelldatei innerhalb des Projekts.
file_tag_nameZeichenketteNeinDer Dateietikett-Name. Falls nicht angegeben, wird der Standard-Datei-Tag des Projekts verwendet.

Antworten

Erfolgsantwort

  • Code: 200 OK
  • Inhaltstyp: application/json
{
  "translation_status": {
    "status": "completed",
    "completeness": 100
  }
}
Antwortschema
FeldTypBeschreibung
translation_status.statusZeichenketteDer aktuelle Verarbeitungsstatus der Quelldatei. Siehe Statuswerte unten.
translation_status.completenessZahlDer Prozentsatz der übersetzten Zeichenketten (0–100). Berechnet als (completed_translatable_strings / total_translatable_strings) × 100.

Statuswerte

Das Feld status kann die folgenden Werte enthalten:

StatusBeschreibung
pendingDie Quelldatei wartet auf die Verarbeitung.
processingDie Übersetzung wird derzeit ausgeführt.
completedAlle Übersetzungen wurden abgeschlossen.
failedBeim Übersetzungsprozess sind Fehler aufgetreten.

Fehlerantworten

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

Beispielanfragen

Basis-Anfrage:

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

Anfrage mit Dateietikett:

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

Codebeispiele

const response = await fetch('https://app.ptc.wpml.org/api/v1/source_files/translation_status?file_path=locales/en.po&file_tag_name=frontend', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(`Translation ${data.translation_status.completeness}% complete`);

import requests

headers = {
    'Content-Type': 'application/json'
}

params = {
    'file_path': 'locales/en.po',
    'file_tag_name': 'frontend'
}

response = requests.get('https://app.ptc.wpml.org/api/v1/source_files/translation_status', 
                       headers=headers, params=params)
data = response.json()
print(f"Translation {data['translation_status']['completeness']}% complete")

<?php
$params = http_build_query([
    'file_path' => 'locales/en.po',
    'file_tag_name' => 'frontend'
]);

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://app.ptc.wpml.org/api/v1/source_files/translation_status?{$params}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json'
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

$data = json_decode($response, true);
echo "Translation " . $data['translation_status']['completeness'] . "% complete";
?>
const axios = require('axios');

const response = await axios.get('https://app.ptc.wpml.org/api/v1/source_files/translation_status', {
  headers: {
    'Content-Type': 'application/json'
  },
  params: {
    file_path: 'locales/en.po',
    file_tag_name: 'frontend'
  }
});

console.log(`Translation ${response.data.translation_status.completeness}% complete`);


Alle Übersetzungen herunterladen

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

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

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

HTTP-Anfrage

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

Parameter

ParameterTypErforderlichBeschreibung
file_pathZeichenketteJaDer Pfad zur Quelldatei innerhalb des Projekts.
file_tag_nameZeichenketteNeinDer Name des Dateietiketts. Wenn kein Dateietikett angegeben wird, wird das Standard-Dateietikett des Projekts verwendet. Eine Quelldatei wird eindeutig durch die Kombination aus file_path und file_tag_name identifiziert.

Antworten

Erfolgsantwort

  • Code: 200 OK
  • Inhaltstyp: application/zip
  • Antworttext: Binäre ZIP-Datei mit Übersetzungsdateien
  • Header:
    • Content-Type: application/zip
    • Content-Disposition: attachment; filename="translations-{source_file_id}.zip"
ZIP-Archivinhalt

Die heruntergeladene ZIP-Datei enthält:

  • Übersetzungsdateien – Eine pro Zielsprache für die angegebene Quelldatei
  • Zusätzliche Übersetzungsdateien – Zusätzliche generierte Dateien (falls konfiguriert), die gemäß Ihren konfigurierten Pfaden auf der Stammebene platziert werden
  • Dateistruktur – Entspricht der Konfiguration, die während der Erstellung der Quelldatei festgelegt wurde

Beispiel für eine ZIP-Struktur:

translations-123.zip
├── locales/es.json
├── locales/fr.json
├── locales/de.json
├── locales/es.po
├── locales/fr.po
├── locales/de.po
├── locales/es.mo
├── locales/fr.mo
├── locales/de.mo

Fehlerantworten

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

Beispielanfragen

Basis-Anfrage:

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

Anfrage mit Dateietikett:

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

Codebeispiele

const response = await fetch('https://app.ptc.wpml.org/api/v1/source_files/download_translations?file_path=locales/en.po&file_tag_name=frontend', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json'
  }
});

if (response.ok) {
  const blob = await response.blob();
  const url = window.URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = 'translations.zip';
  document.body.appendChild(a);
  a.click();
  window.URL.revokeObjectURL(url);
}

import requests

headers = {
    'Content-Type': 'application/json'
}

params = {
    'file_path': 'locales/en.po',
    'file_tag_name': 'frontend'
}

response = requests.get('https://app.ptc.wpml.org/api/v1/source_files/download_translations', 
                       headers=headers, params=params)

if response.status_code == 200:
    with open('translations.zip', 'wb') as f:
        f.write(response.content)
    print("Translations downloaded successfully")
<?php
$params = http_build_query([
    'file_path' => 'locales/en.po',
    'file_tag_name' => 'frontend'
]);

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://app.ptc.wpml.org/api/v1/source_files/download_translations?{$params}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json'
    ],
]);

$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

if ($httpCode === 200) {
    file_put_contents('translations.zip', $response);
    echo "Translations downloaded successfully";
}
?>
const axios = require('axios');
const fs = require('fs');

const response = await axios.get('https://app.ptc.wpml.org/api/v1/source_files/download_translations', {
  headers: {
    'Content-Type': 'application/json'
  },
  params: {
    file_path: 'locales/en.po',
    file_tag_name: 'frontend'
  },
  responseType: 'stream'
});

response.data.pipe(fs.createWriteStream('translations.zip'));
console.log('Translations downloaded successfully');

Quelldateien in großen Mengen 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 umfangreiche Aktualisierungen zu beschleunigen.

Zusätzliche Informationen

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

HTTP-Anfrage

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

Parameter

ParameterTypErforderlichBeschreibung
zip_fileDateiJaEin ZIP-Archiv, das die hochzuladenden Quelldateien enthält. Es muss eine gültige ZIP-Datei sein.
file_tag_nameZeichenketteNeinDer Dateitagname, der allen Quelldateien im Archiv zugeordnet werden soll. Wenn nicht angegeben, wird der Standarddateitag des Projekts verwendet. Jede Quelldatei wird eindeutig durch die Kombination aus file_path und file_tag_name identifiziert.
callback_urlZeichenketteNeinDie URL, die Webhook-Benachrichtigungen empfängt, wenn jede Datei verarbeitet wird.

Erwartete ZIP-Dateistruktur

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

Beispiel für eine 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

  • Code: 200 OK
  • Inhaltstyp: application/json
{
  "success": true,
  "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
FeldTypBeschreibung
successbooleanGibt an, ob der Massen-Upload erfolgreich war.
processed_filesarray[object]Ein Array von Quelldateien, die erfolgreich verarbeitet wurden.
processed_files[].idGanzzahlDie eindeutige Kennung für die erstellte Quelldatei.
processed_files[].file_pathZeichenketteDer Pfad der Quelldatei, wobei die ursprüngliche ZIP-Struktur erhalten bleibt.
processed_files[].created_atZeichenketteEin ISO 8601-Zeitstempel, der angibt, wann die Quelldatei erstellt wurde.
processed_files[].file_tagobjectDie Informationen zum Dateitag.
processed_files[].file_tag.idGanzzahlDie Dateietikett-Kennung.
processed_files[].file_tag.nameZeichenketteDer Dateietikett-Name.
unsupported_filesarray[string]Ein Array von Dateinamen, die nicht in einem unterstützten Format vorliegen.
not_found_filesarray[string]Ein Array von unterstützten Dateien, die keiner vorhandenen Quelldatei entsprachen und ignoriert wurden.

Fehlerantworten

Ungültige ZIP-Datei

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

Verarbeitung fehlgeschlagen

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

Nicht autorisiert

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

Verboten

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

Webhook-Callback

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

Callback-Anfragetext (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": "locale/en.po"
}

Beispielanfragen

Einfacher Massen-Upload:

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files/bulk" \
  -H "Content-Type: multipart/form-data" \
  -F "zip_file=@source-files.zip" \
  -F "file_tag_name=backend"

Anfrage mit Callback-URL:

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

Codebeispiele

const formData = new FormData();
const fileInput = document.getElementById('zip-file-input');
formData.append('zip_file', fileInput.files[0]);
formData.append('file_tag_name', 'backend');
formData.append('callback_url', 'https://your-app.com/webhooks/complete');

const response = await fetch('https://app.ptc.wpml.org/api/v1/source_files/bulk', {
  method: 'POST',
  body: formData
});

const data = await response.json();
console.log(`Processed ${data.processed_files.length} files`);
console.log(`Unsupported files: ${data.unsupported_files.join(', ')}`);

import requests

files = {'zip_file': open('source-files.zip', 'rb')}
data = {
    'file_tag_name': 'backend',
    'callback_url': 'https://your-app.com/webhooks/complete'
}

response = requests.post('https://app.ptc.wpml.org/api/v1/source_files/bulk', 
                        files=files, data=data)
result = response.json()

print(f"Processed {len(result['processed_files'])} files")
print(f"Unsupported files: {', '.join(result['unsupported_files'])}")

<?php
$zip_file_path = 'source-files.zip';
$post_data = [
    'zip_file' => new CURLFile($zip_file_path),
    'file_tag_name' => 'backend',
    'callback_url' => 'https://your-app.com/webhooks/complete'
];

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => 'https://app.ptc.wpml.org/api/v1/source_files/bulk',
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $post_data,
    CURLOPT_RETURNTRANSFER => true,
]);

$response = curl_exec($curl);
curl_close($curl);

$result = json_decode($response, true);
echo "Processed " . count($result['processed_files']) . " files";
?>
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

const formData = new FormData();
formData.append('zip_file', fs.createReadStream('source-files.zip'));
formData.append('file_tag_name', 'backend');
formData.append('callback_url', 'https://your-app.com/webhooks/complete');

const response = await axios.post('https://app.ptc.wpml.org/api/v1/source_files/bulk', formData, {
  headers: formData.getHeaders()
});

console.log(`Processed ${response.data.processed_files.length} files`);
Nach oben scrollen