API für Quelldatei-Uploads, -Ersetzungen, Übersetzungsfortschritt und -Downloads.
Ob Sie eine einzelne Datei verwalten oder einen kontinuierlichen Lokalisierungsworkflow automatisieren, diese API gibt Ihnen die volle Kontrolle über die Inhalte, die Sie zur Übersetzung senden, und wie Sie die Übersetzungen erhalten.
API-Schnelllinks
Endpunkte
Wie die PTC API Quelldateien identifiziert und organisiert
Die PTC API verwendet ein flexibles System, das auf Dateitags 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.
Dateitags
Dateitags sind eine flexible Möglichkeit, Quelldateien in Übersetzungsprojekten zu gruppieren und zu organisieren. Sie können sie wie Kategorien verwenden, um Ihren Workflow-Anforderungen gerecht zu werden. Zum Beispiel können Dateitags 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
Dateitagnamen sind in den meisten API-Operationen optional. Jede Quelldatei hat jedoch immer mindestens einen Tag. Ein Standard-Dateitag wird automatisch erstellt und zugewiesen, wenn ein Projekt eingerichtet wird. Dieses Standardverhalten hält Projekte auch in einfachen Setups organisiert, während es Ihnen dennoch ermöglicht, bei Bedarf komplexere Tagging-Strukturen aufzubauen.
Dateitag-Name + Dateipfad
Jede Quelldatei wird eindeutig durch die Kombination aus ihrem Dateitag-Namen und Dateipfad identifiziert.
- Wenn Sie keinen benutzerdefinierten Dateitag beim Hochladen oder Verarbeiten einer Datei angeben, wird der Standard-Tag automatisch 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 teilen.
Abfrageparameter
Beim Abrufen einer bestimmten Datei können zugehörige Endpunkte Abfrageparameter wie die folgenden akzeptieren:
file_tag_name
– Der mit der Datei verknüpfte Tagfile_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, deren Status überprüfen oder bestimmte Dateien basierend auf Tag, Pfad oder Upload-Methode finden möchten.
HTTP-Anfrage
GET https://app.ptc.wpml.org/api/v1/source_files
Parameter
Parameter | Typ | Erforderlich | Standard | Beschreibung |
---|---|---|---|---|
page | Ganzzahl | Nein | 1 | Die Seitenzahl für die Paginierung. Muss größer als 0 sein. |
per_page | Ganzzahl | Nein | 50 | Die Anzahl der Elemente pro Seite. Muss größer als 0 sein. |
order_by | Zeichenkette | Nein | created_at | Das Feld, nach dem sortiert werden soll. Zulässige Werte: id , created_at , updated_at . |
sort | Zeichenkette | Nein | desc | Die Sortierrichtung. Zulässige Werte: asc , desc . |
file_path | Zeichenkette | Nein | – | Filtert nach exaktem Dateipfad. |
upload_origin | Zeichenkette | Nein | – | Filtert danach, wie die Datei hochgeladen wurde. Zulässige Werte sind: git , manual , api . |
Antworten
Erfolgreiche Antwort
- 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:
Feld | Typ | Beschreibung |
---|---|---|
id | Ganzzahl | Der eindeutige Bezeichner für die Quelldatei. |
file_path | Zeichenkette | Der Pfad zur Quelldatei innerhalb des Projekts. |
translation_path | Zeichenkette | Das Muster, wo übersetzte Dateien gespeichert werden sollen. |
additional_translation_files | array[string] | Die Pfade für zusätzliche Ausgabedateien. |
status | Zeichenkette | Der aktuelle Verarbeitungsstatus der Quelldatei. |
upload_origin | Zeichenkette | Wie die Datei hochgeladen wurde (git , manual , api ). |
created_at | Zeichenkette | Ein ISO 8601 Zeitstempel, der angibt, wann die Quelldatei ursprünglich erstellt wurde. |
updated_at | Zeichenkette | Ein ISO 8601 Zeitstempel, der angibt, wann die Quelldatei zuletzt aktualisiert wurde. |
file_tag | object | Informationen zum Dateitag. |
file_tag.id | Ganzzahl | Der Dateitag-Bezeichner. |
file_tag.name | Zeichenkette | Der Dateitag-Name. |
download_url | Zeichenkette | Die URL zum Herunterladen von Übersetzungen für diese Quelldatei. |
Paginierungsobjekt:
Feld | Typ | Beschreibung |
---|---|---|
page | Ganzzahl | Die aktuelle Seitenzahl. |
per_page | Ganzzahl | Die Anzahl der Elemente pro Seite. |
total | Ganzzahl | Die Gesamtzahl der Quelldateien. |
total_pages | Ganzzahl | Die Gesamtzahl der Seiten. |
has_next_page | Boolean | Ob eine nächste Seite verfügbar ist. |
has_previous_page | Boolean | Ob 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
Grundlegende 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);
Übersetzungsstrings abrufen
Ruft alle übersetzbaren Strings aus einer bestimmten Quelldatei ab, zusammen mit ihren bestehenden Übersetzungen in allen Zielsprachen.
Dieser Endpunkt ist nützlich, um Inhalte abzurufen, die übersetzt werden müssen oder bereits übersetzt wurden. Die Quelldatei wird identifiziert durch file_path
und file_tag_name
.
HTTP-Anfrage
GET https://app.ptc.wpml.org/api/v1/source_files/translation_strings
Parameter
Parameter | Typ | Erforderlich | Standard | Beschreibung |
---|---|---|---|---|
file_path | Zeichenkette | Ja | – | Der Pfad zur Quelldatei innerhalb des Projekts. |
file_tag_name | Zeichenkette | Nein | – | Der Dateitag-Name. Wird er nicht angegeben, wird der Standard-Tag des Projekts verwendet. |
page | Ganzzahl | Nein | 1 | Die Seitenzahl für die Paginierung (als Cursor verwendet). Muss größer als 0 sein. |
q | Zeichenkette | Nein | – | Die Suchanfrage zum Filtern von Übersetzungsstrings nach ihrem Quelltext. |
Antworten
Erfolgreiche Antwort
- 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
Feld | Typ | Beschreibung |
---|---|---|
total_strings_count | Ganzzahl | Die Gesamtzahl der übersetzbaren Strings in der Quelldatei. |
translation_strings | Array[Objekt] | Das Array von Übersetzungsstring-Objekten (paginiert, max. 500 pro Seite). |
translation_strings[].source | Zeichenkette | Der ursprüngliche Quelltext, der übersetzt werden soll. |
translation_strings[].translations | object | Ein Hash von Übersetzungen, bei dem die Schlüssel Sprach-ISO-Codes sind und die Werte der übersetzte Text sind. |
cursor | Ganzzahl | Der 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
Grundlegende 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 Dateitag:
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);
Quelldatei erstellen
Registriert eine neue Quelldatei in Ihrem Projekt, damit sie zur Übersetzung bereit ist.
Dieser Endpunkt erstellt den Dateieintrag und richtet dessen Übersetzungskonfiguration ein, fügt aber den eigentlichen Dateiinhalt nicht 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
Parameter | Typ | Erforderlich | Beschreibung |
---|---|---|---|
file_path | Zeichenkette | Ja | Der Pfad, unter dem die Quelldatei im Projekt gespeichert werden soll. Muss eine unterstützte Erweiterung haben. |
output_file_path | Zeichenkette | Ja | Das Ausgabepfad-Muster für übersetzte Dateien. Verwenden Sie {{lang}} als Placeholder für den Sprachcode. |
translations | Array[Objekt] | Nein | Die bereits vorhandenen Übersetzungsdateien, die zusammen mit der Quelldatei hochgeladen werden sollen. Diese Dateien werden wie bereitgestellt gespeichert, und ihre Strings werden von PTC nicht erneut übersetzt. Beachten Sie, dass die Bereitstellung bestehender Übersetzungen nicht empfohlen wird, da PTC bessere Ergebnisse erzielt, wenn es den vollständigen Kontext Ihres Projekts nutzen und von Grund auf neu übersetzen kann. |
translations[].target_language_iso | Zeichenkette | Ja | Der 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[].file | Datei | Ja | Die hochzuladende Übersetzungsdatei. |
additional_translation_files | Array[Objekt] | Nein | Zusätzliche Ausgabedateikonfigurationen für bestimmte Formate. Um zu sehen, welche Formate zusätzliche Ausgabedateien unterstützen, lesen Sie den Endpunkt Unterstützte Dateiformate auflisten. Bei nicht unterstützten Formaten wird dieses Feld ignoriert. |
additional_translation_files[].type | Zeichenkette | Ja | Weitere Details finden Sie unter unterstützte Dateiformate. |
additional_translation_files[].path | Zeichenkette | Ja | Das Pfadmuster für die Datei. |
Antworten
Erfolgreiche Antwort
- 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
Feld | Typ | Beschreibung |
---|---|---|
source_file.id | Ganzzahl | Der eindeutige Bezeichner für die erstellte Quelldatei. |
source_file.file_path | Zeichenkette | Der Pfad der Quelldatei innerhalb des Projekts. |
source_file.created_at | Zeichenkette | Ein ISO 8601 Zeitstempel, der angibt, wann die Quelldatei ursprünglich erstellt wurde. |
source_file.file_tag.id | Ganzzahl | Der Dateitag-Bezeichner. |
source_file.file_tag.name | Zeichenkette | Der Dateitag-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
Grundlegende Quelldateierstellung:
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 existieren. Falls Sie sie noch nicht erstellt haben, siehe Quelldatei erstellen.
HTTP-Anfrage
PUT https://app.ptc.wpml.org/api/v1/source_files/process
Parameter
Parameter | Typ | Erforderlich | Beschreibung |
---|---|---|---|
file | Datei | Ja | Die 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_path | Zeichenkette | Ja | Der Pfad zur bestehenden Quelldatei im Projekt, die aktualisiert werden soll. |
file_tag_name | Zeichenkette | Nein | Der Name des Dateitags, der der Quelldatei zugeordnet ist. Falls nicht angegeben, wird der Standard-Dateitag des Projekts verwendet. |
callback_url | Zeichenkette | Nein | Die URL, die Webhook-Benachrichtigungen erhält, wenn die Dateiverarbeitung abgeschlossen ist. |
Antworten
Erfolgreiche Antwort
- 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
Feld | Typ | Beschreibung |
---|---|---|
source_file.id | Ganzzahl | Die eindeutige Kennung für die verarbeitete Quelldatei. |
source_file.file_path | Zeichenkette | Der Pfad der Quelldatei innerhalb des Projekts. |
source_file.created_at | Zeichenkette | Ein ISO 8601 Zeitstempel, der angibt, wann die Quelldatei ursprünglich erstellt wurde. |
source_file.file_tag.id | Ganzzahl | Der Dateitag-Bezeichner. |
source_file.file_tag.name | Zeichenkette | Der Dateitag-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
- Voraussetzung: Die Quelldatei muss bereits über Quelldatei erstellen erstellt worden sein.
- Dateiupload: Neuer Inhalt wird hochgeladen und ersetzt den bestehenden Dateiinhalt.
- Verarbeitung: Die neuen übersetzbaren Zeichenketten werden extrahiert und automatisch übersetzt.
- 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.
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 bei langwierigen Aufgaben
- UI-Updates – 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
Parameter | Typ | Erforderlich | Beschreibung |
---|---|---|---|
file_path | Zeichenkette | Ja | Der Pfad zur Quelldatei innerhalb des Projekts. |
file_tag_name | Zeichenkette | Nein | Der Dateitag-Name. Falls nicht angegeben, wird der Standard-Datei-Tag des Projekts verwendet. |
Antworten
Erfolgreiche Antwort
- Code:
200 OK
- Inhaltstyp:
application/json
{
"translation_status": {
"status": "completed",
"completeness": 100
}
}
Antwortschema
Feld | Typ | Beschreibung |
---|---|---|
translation_status.status | Zeichenkette | Der aktuelle Verarbeitungsstatus der Quelldatei. Siehe Statuswerte unten. |
translation_status.completeness | Zahl | Der Prozentsatz der übersetzten Zeichenketten (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 in Bearbeitung. |
completed | Alle Übersetzungen wurden abgeschlossen. |
failed | Der Übersetzungsprozess ist auf Fehler gestoßen. |
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
Grundlegende 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 Dateitag:
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
Parameter | Typ | Erforderlich | Beschreibung |
---|---|---|---|
file_path | Zeichenkette | Ja | Der Pfad zur Quelldatei innerhalb des Projekts. |
file_tag_name | Zeichenkette | Nein | Der Dateitag-Name. Falls nicht angegeben, wird der Standard-Dateitag des Projekts verwendet. Eine Quelldatei wird eindeutig durch die Kombination von file_path und file_tag_name identifiziert. |
Antworten
Erfolgreiche Antwort
- 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"
Inhalt des ZIP-Archivs
Die heruntergeladene ZIP-Datei enthält:
- Übersetzungsdateien – Eine pro Zielsprache für die angegebene Quelldatei
- Zusätzliche Übersetzungsdateien – Zusätzlich generierte Dateien (falls konfiguriert), die auf der Stammebene gemäß Ihren konfigurierten Pfaden abgelegt werden
- Dateistruktur – Entspricht der bei der Erstellung der Quelldatei festgelegten Konfiguration
Beispiel-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
Grundlegende 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 Dateitag:
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 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 erkannt.
Dies ist die Stapelversion 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 Übersetzungen werden erneut ausgelöst.
- Wenn eine Datei unterstützt wird, aber keiner bestehenden Quelldatei entspricht, 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. - Große Archive können 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 Stapel aufzuteilen. Alle Dateien im Archiv werden automatisch zur Übersetzung freigegeben.
- 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 Pfadprobleme verursachen könnten.
- Wenn ein
callback_url
bereitgestellt wird, wird einePOST
Anfrage für jede verarbeitete Quelldatei mit ihren Ergebnissen gesendet.
HTTP-Anfrage
POST https://app.ptc.wpml.org/api/v1/source_files/bulk
Parameter
Parameter | Typ | Erforderlich | Beschreibung |
---|---|---|---|
zip_file | Datei | Ja | Ein ZIP-Archiv, das die hochzuladenden Quelldateien enthält. Es muss eine gültige ZIP-Datei sein. |
file_tag_name | Zeichenkette | Nein | Der Dateitag-Name, der allen Quelldateien im Archiv zugeordnet werden soll. Falls nicht angegeben, wird der Standard-Dateitag des Projekts verwendet. Jede Quelldatei wird eindeutig durch die Kombination aus file_path und file_tag_name identifiziert. |
callback_url | Zeichenkette | Nein | Die URL, die Webhook-Benachrichtigungen empfängt, wenn jede Datei verarbeitet wird. |
Erwartete ZIP-Dateistruktur
Die ZIP-Datei kann Quelldateien in jeder beliebigen Verzeichnisstruktur enthalten. Die Verzeichnisstruktur wird beibehalten und Dateien werden rekursiv verarbeitet.
Beispiel-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
Erfolgreiche Antwort
- 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
Feld | Typ | Beschreibung |
---|---|---|
success | Boolean | Ob der Massen-Upload-Vorgang erfolgreich war. |
processed_files | Array[Objekt] | Ein Array von Quelldateien, die erfolgreich verarbeitet wurden. |
processed_files[].id | Ganzzahl | Der eindeutige Bezeichner für die erstellte Quelldatei. |
processed_files[].file_path | Zeichenkette | Der Pfad der Quelldatei, unter Beibehaltung der ursprünglichen ZIP-Struktur. |
processed_files[].created_at | Zeichenkette | Ein ISO 8601 Zeitstempel, der angibt, wann die Quelldatei erstellt wurde. |
processed_files[].file_tag | object | Die Dateitag-Informationen. |
processed_files[].file_tag.id | Ganzzahl | Der Dateitag-Bezeichner. |
processed_files[].file_tag.name | Zeichenkette | Der Dateitag-Name. |
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 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
bereitgestellt wird, wird eine POST
Anfrage für jede verarbeitete Datei gesendet.
Callback-Anfrage-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": "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`);