API: téléversez, remplacez, suivez, téléchargez.
Que vous gériez un seul fichier ou que vous automatisiez un flux de travail de localisation continue, cette API vous donne un contrôle total sur le contenu que vous envoyez pour la traduction et sur la façon dont vous recevez les traductions.
Liens rapides de l’API
Points de terminaison
Comment l’API PTC identifie et organise les fichiers source
L’API PTC utilise un système flexible basé sur les balises de fichier et les chemins de fichier. Ces paramètres fonctionnent ensemble pour garantir que chaque fichier que vous téléversez, mettez à jour ou demandez est clairement défini et facile à gérer.
Balises de fichier
Les balises de fichier sont un moyen flexible de regrouper et d’organiser les fichiers source dans les projets de traduction. Vous pouvez les utiliser comme des catégories pour répondre aux besoins de votre flux de travail. Par exemple, les balises de fichier peuvent indiquer :
- Contrôle de version :
v1.0,beta,production - Branches de fonctionnalité :
user-auth,dashboard-redesign - Contexte de l’application :
mobile-app,admin-panel,marketing - Propriété de l’équipe :
frontend-team,content-team - État du flux de travail :
approved,pending-review,priority-high
Les noms de balises de fichier sont facultatifs dans la plupart des opérations de l’API. Cependant, chaque fichier source a toujours au moins une balise. Une balise de fichier par défaut est automatiquement créée et attribuée lorsqu’un projet est configuré. Ce comportement par défaut permet de maintenir les projets organisés, même dans les configurations simples, tout en vous permettant de créer des structures de balisage plus avancées si nécessaire.
Nom de la balise de fichier + chemin du fichier
Chaque fichier source est identifié de manière unique par la combinaison de son nom de balise de fichier et de son chemin de fichier.
- Si vous ne fournissez pas de balise de fichier personnalisée lors du téléversement ou du traitement d’un fichier, la balise par défaut sera attribuée automatiquement.
- Le nom de la balise + le chemin d’un fichier définissent ensemble son identité. Cette combinaison garantit que chaque fichier est unique dans votre projet, même si différentes versions ou différents contextes partagent le même chemin de fichier.
Paramètres de requête
Lors de la récupération d’un fichier spécifique, les points de terminaison associés peuvent accepter des paramètres de requête tels que :
file_tag_name– La balise associée au fichierfile_path– Le chemin d’accès au fichier
Ces paramètres vous permettent de localiser et de récupérer précisément les fichiers corrects de votre projet.
Lister tous les fichiers source du projet
Liste tous les fichiers source de votre projet, avec des options pour filtrer, trier et paginer les résultats. Ceci est utile lorsque vous souhaitez parcourir vos fichiers, vérifier leur état ou trouver des fichiers spécifiques en fonction de la balise, du chemin ou de la méthode de téléversement.
Requête HTTP
GET https://app.ptc.wpml.org/api/v1/source_filesParamètres
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
page | entier | Non | 1 | Le numéro de page pour la pagination. Doit être supérieur à 0. |
per_page | entier | Non | 50 | Le nombre d’éléments par page. Doit être supérieur à 0. |
order_by | chaîne de caractères | Non | created_at | Le champ de tri. Valeurs autorisées : id, created_at, updated_at. |
sort | chaîne de caractères | Non | desc | Le sens du tri. Valeurs autorisées : asc, desc. |
file_path | chaîne de caractères | Non | – | Filtre par chemin de fichier exact. |
upload_origin | chaîne de caractères | Non | – | Filtre par la façon dont le fichier a été téléversé. Les valeurs autorisées incluent : git, manual, api. |
Réponses
Réponse de succès
- Code :
200 OK - Type de contenu :
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
}
}
Schéma de réponse
Objet fichier source :
| Champ | Type | Description |
|---|---|---|
id | entier | L’identifiant unique du fichier source. |
file_path | chaîne de caractères | Le chemin d’accès au fichier source dans le projet. |
translation_path | chaîne de caractères | Le modèle d’emplacement où les fichiers traduits doivent être enregistrés. |
additional_translation_files | tableau[chaîne] | Les chemins d’accès à tous les fichiers de sortie supplémentaires. |
status | chaîne de caractères | L’état de traitement actuel du fichier source. |
upload_origin | chaîne de caractères | Comment le fichier a été téléversé (git, manual, api). |
created_at | chaîne de caractères | Un horodatage ISO 8601 indiquant la date de création du fichier source. |
updated_at | chaîne de caractères | Un horodatage ISO 8601 indiquant la dernière mise à jour du fichier source. |
file_tag | objet | Informations sur la balise de fichier. |
file_tag.id | entier | L’identifiant de la balise de fichier. |
file_tag.name | chaîne de caractères | Le nom de la balise de fichier. |
download_url | chaîne de caractères | L’URL pour télécharger les traductions de ce fichier source. |
Objet de pagination :
| Champ | Type | Description |
|---|---|---|
page | entier | Le numéro de la page actuelle. |
per_page | entier | Le nombre d’éléments par page. |
total | entier | Le nombre total de fichiers source. |
total_pages | entier | Le nombre total de pages. |
has_next_page | boolean | Indique s’il existe une page suivante disponible. |
has_previous_page | boolean | Indique s’il existe une page précédente disponible. |
Réponses d’erreur
Non autorisé
- Code :
401 Unauthorized
{
"error": "Unauthorized access. Please provide a valid API token."
}
Interdit
- Code :
403 Forbidden
{
"error": "Access denied. Insufficient permissions."
}
Paramètres non valides
- Code :
422 Unprocessable Entity
{
"error": "Invalid parameters provided."
}
Exemples de requêtes
Requête de base :
curl -X GET "https://app.ptc.wpml.org/api/v1/source_files" \
-H "Content-Type: application/json"Requête filtrée :
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"
Exemples de code
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);
Obtenir les chaînes de traduction
Récupère toutes les chaînes traduisibles d’un fichier source spécifique, ainsi que leurs traductions existantes dans toutes les langues cibles.
Ce point de terminaison est utile pour extraire le contenu qui doit être traduit ou qui l’a déjà été. Le fichier source est identifié par file_path et file_tag_name.
Requête HTTP
GET https://app.ptc.wpml.org/api/v1/source_files/translation_stringsParamètres
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
file_path | chaîne de caractères | Oui | – | Le chemin d’accès au fichier source dans le projet. |
file_tag_name | chaîne de caractères | Non | – | Le nom de la balise de fichier. S’il n’est pas fourni, la balise par défaut du projet est utilisée. |
page | entier | Non | 1 | Le numéro de page pour la pagination (utilisé comme curseur). Doit être supérieur à 0. |
q | chaîne de caractères | Non | – | La requête de recherche pour filtrer les chaînes de traduction par leur texte source. |
Réponses
Réponse de succès
- Code :
200 OK - Type de contenu :
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
}
Schéma de réponse
| Champ | Type | Description |
|---|---|---|
total_strings_count | entier | Le nombre total de chaînes traduisibles dans le fichier source. |
translation_strings | array[object] | Le tableau d’objets de chaîne de traduction (paginé, max. 500 par page). |
translation_strings[].source | chaîne de caractères | Le texte source original à traduire. |
translation_strings[].translations | objet | Un hachage de traductions où les clés sont des codes ISO de langue et les valeurs sont le texte traduit. |
cursor | entier | Le curseur de page actuel utilisé pour la pagination. |
Réponses d’erreur
Fichier source introuvable
- Code :
404 Not Found
{
"error": "Source file not found"
}
Non autorisé
- Code :
401 Unauthorized
{
"error": "Unauthorized access. Please provide a valid API token."
}
Interdit
- Code :
403 Forbidden
{
"error": "Access denied. Insufficient permissions."
}
Paramètres non valides
- Code :
422 Unprocessable Entity
{
"error": "Invalid parameters provided."
}
Exemples de requêtes
Requête de base :
curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/translation_strings?file_path=locales/en.po" \
-H "Content-Type: application/json"Une requête avec une balise de fichier :
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"
Une requête avec pagination et recherche :
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"
Exemples de code
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);
Créer le fichier source
Enregistre un nouveau fichier source dans votre projet afin qu’il soit prêt pour la traduction.
Ce point de terminaison crée l’entrée de fichier et configure sa configuration de traduction, mais n’attache pas le contenu réel du fichier.
Après avoir créé le fichier, vous devrez utiliser le point de terminaison Traiter le fichier source pour télécharger le contenu et démarrer le processus de traduction.
Requête HTTP
POST https://app.ptc.wpml.org/api/v1/source_files
Paramètres
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
file_path | chaîne de caractères | Oui | Le chemin d’accès où le fichier source doit être stocké dans le projet. Doit avoir une extension prise en charge. |
output_file_path | chaîne de caractères | Oui | Le modèle de chemin de sortie pour les fichiers traduits. Utilisez {{lang}} comme placeholder pour le code de langue. |
translations | array[object] | Non | Les fichiers de traduction préexistants à téléverser avec le fichier source. Ces fichiers seront stockés tels quels, et leurs chaînes ne seront pas retraduites par PTC. Notez qu’il n’est pas recommandé de fournir des traductions existantes, car PTC produit de meilleurs résultats lorsqu’il peut utiliser le contexte complet de votre projet et traduire à partir de zéro. |
translations[].target_language_iso | chaîne de caractères | Oui | Le code ISO de la langue cible pour cette traduction. Vous pouvez trouver la liste complète des langues prises en charge et de leurs codes ISO dans le point de terminaison Lister toutes les langues cibles. |
translations[].file | file | Oui | Le fichier de traduction à téléverser. |
additional_translation_files | array[object] | Non | Configurations de fichiers de sortie supplémentaires pour des formats spécifiques. Pour voir quels formats prennent en charge des fichiers de sortie supplémentaires, consultez le point de terminaison Lister les formats de fichiers pris en charge. Pour les formats non pris en charge, ce champ sera ignoré. |
additional_translation_files[].type | chaîne de caractères | Oui | Voir les formats de fichiers pris en charge pour plus de détails. |
additional_translation_files[].path | chaîne de caractères | Oui | Le modèle de chemin d’accès au fichier. |
Réponses
Réponse de succès
- Code :
201 Created - Type de contenu :
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"
}
}
}
Schéma de réponse
| Champ | Type | Description |
|---|---|---|
source_file.id | entier | L’identifiant unique du fichier source créé. |
source_file.file_path | chaîne de caractères | Le chemin d’accès du fichier source dans le projet. |
source_file.created_at | chaîne de caractères | Un horodatage ISO 8601 indiquant la date de création du fichier source. |
source_file.file_tag.id | entier | L’identifiant de la balise de fichier. |
source_file.file_tag.name | chaîne de caractères | Le nom de la balise de fichier. |
Réponses d’erreur
Échec de la validation
- Code :
422 Unprocessable Entity
{
"success": false,
"error": "Source file creation failed"
}
Non autorisé
- Code :
401 Unauthorized
{
"error": "Unauthorized access. Please provide a valid API token."
}
Interdit
- Code :
403 Forbidden
{
"error": "Access denied. Insufficient permissions."
}
Exemples de requêtes
Création de fichier source de base :
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"
Requête avec URL de rappel :
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"Requête avec des traductions préexistantes :
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"
Requête avec des fichiers de sortie supplémentaires :
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"
Exemples de code
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"
}
Traiter le fichier source
Télécharge le contenu vers un fichier source existant et démarre le processus de traduction.
Ce point de terminaison remplace le contenu actuel du fichier, met à jour les chaînes traduisibles stockées et démarre la traduction automatique.
Pour utiliser ce point de terminaison, le fichier source doit déjà exister dans le projet. Si vous ne l’avez pas encore créé, consultez Créer le fichier source.
Requête HTTP
PUT https://app.ptc.wpml.org/api/v1/source_files/process
Paramètres
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
file | file | Oui | Le fichier source à télécharger. Le contenu du fichier est validé pour s’assurer qu’il correspond à son extension déclarée. Par exemple, si l’extension du fichier est .json, le contenu téléchargé doit être un JSON valide. |
file_path | chaîne de caractères | Oui | Le chemin d’accès au fichier source existant dans le projet qui doit être mis à jour. |
file_tag_name | chaîne de caractères | Non | Le nom de la balise de fichier associée au fichier source. S’il n’est pas fourni, la balise de fichier par défaut du projet est utilisée. |
callback_url | chaîne de caractères | Non | L’URL qui reçoit les notifications de webhook lorsque le traitement du fichier est terminé. |
Réponses
Réponse de succès
- Code :
200 OK - Type de contenu :
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"
}
}
}
Schéma de réponse
| Champ | Type | Description |
|---|---|---|
source_file.id | entier | L’identifiant unique du fichier source traité. |
source_file.file_path | chaîne de caractères | Le chemin d’accès du fichier source dans le projet. |
source_file.created_at | chaîne de caractères | Un horodatage ISO 8601 indiquant la date de création du fichier source. |
source_file.file_tag.id | entier | L’identifiant de la balise de fichier. |
source_file.file_tag.name | chaîne de caractères | Le nom de la balise de fichier. |
Réponses d’erreur
Fichier source introuvable
- Code :
422 Unprocessable Entity
{
"errors": {
"file": ["File format is invalid or not supported"]
}
}
Non autorisé
- Code :
401 Unauthorized
{
"error": "Unauthorized access. Please provide a valid API token."
}
Interdit
- Code :
403 Forbidden
{
"error": "Access denied. Insufficient permissions."
}
Flux de travail
- Prérequis : Le fichier source doit déjà être créé via Créer le fichier source.
- Téléchargement du fichier : Le nouveau contenu est téléchargé et remplace le contenu du fichier existant.
- Traitement : Les nouvelles chaînes traduisibles sont extraites et traduites automatiquement.
- Rappel : Une notification de webhook facultative est envoyée lorsque le traitement est terminé.
Rappel de webhook
Lorsqu’un callback_url est fourni, PTC enverra une requête POST à cette URL lorsque le traitement sera terminé.
Corps de la requête de rappel :
{
"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"
}
Exemples de requêtes
Traitement de fichier de base :
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"
Requête avec URL de rappel :
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"Exemples de code
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);
Formats de fichiers pris en charge
Le point de terminaison prend en charge divers formats de fichiers traduisibles, notamment les fichiers JSON, PO/POT, XLIFF et Properties, entre autres.
La validation du format de fichier a lieu lors du téléchargement pour garantir la compatibilité.
Utilisez le point de terminaison Lister les formats de fichiers pris en charge pour obtenir la liste complète des formats pris en charge.
Obtenir l’état de la traduction
Récupère la progression actuelle de la traduction pour un fichier source spécifique, y compris la quantité terminée et son état de traitement global.
Ceci est utile pour :
- Surveillance de la progression – Suivi de la progression de la traduction pour les tâches de longue durée
- Mises à jour de l’interface utilisateur – Affichage des pourcentages d’achèvement dans votre application
- Intégration du flux de travail – Déclenchement d’actions lorsque la traduction atteint un seuil défini
Requête HTTP
GET https://app.ptc.wpml.org/api/v1/source_files/translation_statusParamètres
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
file_path | chaîne de caractères | Oui | Le chemin d’accès au fichier source dans le projet. |
file_tag_name | chaîne de caractères | Non | Le nom de la balise de fichier. S’il n’est pas fourni, le tag de fichier par défaut du projet est utilisé. |
Réponses
Réponse de succès
- Code :
200 OK - Type de contenu :
application/json
{
"translation_status": {
"status": "completed",
"completeness": 100
}
}
Schéma de réponse
| Champ | Type | Description |
|---|---|---|
translation_status.status | chaîne de caractères | L’état de traitement actuel du fichier source. Voir les valeurs d’état ci-dessous. |
translation_status.completeness | nombre | Le pourcentage de chaînes traduites (0–100). Calculé comme (completed_translatable_strings / total_translatable_strings) × 100. |
Valeurs de statut
Le champ status peut contenir les valeurs suivantes :
| Statut | Description |
|---|---|
pending | Le fichier source est en attente de traitement. |
processing | La traduction est actuellement en cours. |
completed | Toutes les traductions ont été effectuées. |
failed | Le processus de traduction a rencontré des erreurs. |
Réponses d’erreur
Fichier source introuvable
- Code :
404 Not Found
{
"error": "Source file not found"
}
Non autorisé
- Code :
401 Unauthorized
{
"error": "Unauthorized access. Please provide a valid API token."
}
Interdit
- Code :
403 Forbidden
{
"error": "Access denied. Insufficient permissions."
}
Paramètres non valides
- Code :
422 Unprocessable Entity
{
"error": "Invalid parameters provided."
}
Exemples de requêtes
Requête de base :
curl -X GET "https://app.ptc.wpml.org/api/v1/source_files/translation_status?file_path=locales/en.po" \
-H "Content-Type: application/json"
Requête avec balise de fichier :
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"
Exemples de code
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`);
Télécharger toutes les traductions
Télécharge tous les fichiers traduits pour un fichier source spécifique sous forme d’archive ZIP.
Ce point de terminaison crée et renvoie une archive compressée contenant tous les fichiers de traduction dans les langues cibles pour le fichier source spécifié.
Si aucune traduction n’est disponible pour le fichier, la requête renverra une erreur 404 Non trouvé.
Requête HTTP
GET https://app.ptc.wpml.org/api/v1/source_files/download_translations
Paramètres
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
file_path | chaîne de caractères | Oui | Le chemin d’accès au fichier source dans le projet. |
file_tag_name | chaîne de caractères | Non | Le nom de la balise de fichier. S’il n’est pas fourni, la balise de fichier par défaut du projet est utilisée. Un fichier source est identifié de manière unique par la combinaison de file_path et file_tag_name. |
Réponses
Réponse de succès
- Code :
200 OK - Type de contenu :
application/zip - Corps de la réponse : Fichier ZIP binaire contenant les fichiers de traduction
- En-têtes :
Content-Type: application/zipContent-Disposition: attachment; filename="translations-{source_file_id}.zip"
Contenu de l’archive ZIP
Le fichier ZIP téléchargé contient :
- Fichiers de traduction – Un par langue cible pour le fichier source spécifié
- Fichiers de traduction supplémentaires – Fichiers générés supplémentaires (si configurés), placés au niveau racine en suivant vos chemins configurés
- Structure de fichiers – Correspond à la configuration définie lors de la création du fichier source
Exemple de structure ZIP :
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
Réponse de statut
Traductions en cours
- Code :
202 Accepted - En-tête :
Retry-After: 30
{
"status": "processing",
"message": "Translations are still in progress. Please retry after the specified delay.",
"retry_after": 30
}PTC traite les traductions de manière asynchrone. Il y a généralement un court délai entre le téléversement d’un fichier source et la disponibilité des traductions au téléchargement.
Dans ce cas, attendez le nombre de secondes indiqué dans Retry-After.
Réponses d’erreur
Fichier source introuvable
- Code :
404 Not Found
{
"error": "Source file not found"
}
Aucune traduction disponible
- Code :
404 Not Found
{
"error": "No translations are available for this source file"
}
Non autorisé
- Code :
401 Unauthorized
{
"error": "Unauthorized access. Please provide a valid API token."
}
Interdit
- Code :
403 Forbidden
{
"error": "Access denied. Insufficient permissions."
}
Paramètres non valides
- Code :
422 Unprocessable Entity
{
"error": "Invalid parameters provided."
}
Exemples de requêtes
Requête de base :
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
Requête avec balise de fichier :
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
Exemples de code
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');
Télécharger les fichiers source en bloc
Télécharge une archive ZIP contenant plusieurs fichiers traduisibles. Chaque fichier de l’archive est extrait, validé et traité. Les formats pris en charge sont identifiés automatiquement.
Il s’agit de la version de lot de Traiter le fichier source, conçue pour accélérer les mises à jour à grande échelle.
Informations supplémentaires
- Si un fichier correspond à un fichier source existant, il est mis à jour avec le nouveau contenu, et les traductions sont déclenchées à nouveau.
- Si un fichier est pris en charge, mais ne correspond à aucun fichier source existant, il est ajouté à la liste
not_found_fileset ignoré. - Les fichiers avec des formats non pris en charge sont répertoriés sous
unsupported_fileset ignorés. - Les fichiers avec un contenu non valide sont également répertoriés sous
unsupported_fileset ignorés. - Les archives volumineuses peuvent prendre plus de temps à traiter. Les fichiers sont traités un par un pour gérer les ressources, il est donc préférable de diviser les très gros téléchargements (plus de 100 fichiers) en lots plus petits. Tous les fichiers de l’archive sont définis pour être traduits automatiquement.
- Le ZIP téléchargé doit être valide et lisible. Tous les fichiers à l’intérieur doivent être dans un format pris en charge. Les noms de fichiers ne doivent pas inclure de caractères spéciaux qui pourraient causer des problèmes de chemin d’accès.
- Si un
callback_urlest fourni, une requêtePOSTest envoyée pour chaque fichier source traité avec ses résultats.
Requête HTTP
POST https://app.ptc.wpml.org/api/v1/source_files/bulk
Paramètres
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
zip_file | file | Oui | Une archive ZIP contenant les fichiers source à télécharger. Il doit s’agir d’un fichier ZIP valide. |
file_tag_name | chaîne de caractères | Non | Nom de la balise de fichier à associer à tous les fichiers source de l’archive. Si elle n’est pas spécifiée, la balise de fichier par défaut du projet est utilisée. Chaque fichier source est identifié de manière unique par la combinaison de file_path et file_tag_name. |
callback_url | chaîne de caractères | Non | L’URL qui reçoit les notifications de webhook lorsque chaque fichier est traité. |
Structure de fichier ZIP attendue
Le fichier ZIP peut contenir des fichiers source dans n’importe quelle structure de répertoire. La structure de répertoire est conservée et les fichiers sont traités de manière récursive.
Exemple de structure ZIP :
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)
Types de fichiers pris en charge :
- JSON : fichiers
.json - Gettext : fichiers
.po,.pot - Properties : fichiers
.properties - YAML : fichiers
.yml,.yaml - XML : fichiers
.xml - Strings : fichiers
.strings - XLIFF : fichiers
.xliff,.xlf - CSV : fichiers
.csv - PHP : fichiers
.php
Réponses
Réponse de succès
- Code :
200 OK - Type de contenu :
application/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"]
}
Schéma de réponse
| Champ | Type | Description |
|---|---|---|
success | boolean | Indique si l’opération de chargement groupé a réussi. |
file_tag | objet | Les informations de la balise de fichier. |
file_tag.id | entier | L’identifiant de la balise de fichier. |
file_tag.name | chaîne de caractères | Le nom de la balise de fichier. |
processed_files | array[object] | Un tableau de fichiers source qui ont été traités avec succès. |
processed_files[].id | entier | L’identifiant unique du fichier source créé. |
processed_files[].file_path | chaîne de caractères | Le chemin d’accès du fichier source, en conservant la structure ZIP d’origine. |
processed_files[].created_at | chaîne de caractères | Un horodatage ISO 8601 indiquant la date de création du fichier source. |
processed_files[].file_tag | objet | Les informations de la balise de fichier. |
processed_files[].file_tag.id | entier | L’identifiant de la balise de fichier. |
processed_files[].file_tag.name | chaîne de caractères | Le nom de la balise de fichier. |
unsupported_files | tableau[chaîne] | Un tableau de noms de fichiers qui ne sont pas dans un format pris en charge. |
not_found_files | tableau[chaîne] | Un tableau de fichiers pris en charge qui ne correspondaient à aucun fichier source existant et ont été ignorés. |
Réponses d’erreur
Fichier ZIP non valide
- Code :
422 Unprocessable Entity
{
"success": false,
"error": "File format is invalid",
"processed_files": [],
"unsupported_files": []
}
Le traitement a échoué
- Code :
422 Unprocessable Entity
{
"success": false,
"error": "Failed to process ZIP archive",
"processed_files": [],
"unsupported_files": []
}
Non autorisé
- Code :
401 Unauthorized
{
"error": "Unauthorized access. Please provide a valid API token."
}
Interdit
- Code :
403 Forbidden
{
"error": "Access denied. Insufficient permissions."
}
Rappel de webhook
Lorsqu’une callback_url est fournie, une requête POST est envoyée pour chaque fichier traité.
Corps de la requête de rappel (par fichier) :
{
"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"
}
Exemples de requêtes
Chargement groupé de base :
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"
Requête avec URL de rappel :
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"Exemples de code
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`);