Téléversez et gérez les fichiers source via l’API

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.

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 fichier
  • file_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_files

Paramètres

ParamètreTypeObligatoirePar défautDescription
pageentierNon1Le numéro de page pour la pagination. Doit être supérieur à 0.
per_pageentierNon50Le nombre d’éléments par page. Doit être supérieur à 0.
order_bychaîne de caractèresNoncreated_atLe champ de tri. Valeurs autorisées : id, created_at, updated_at.
sortchaîne de caractèresNondescLe sens du tri. Valeurs autorisées : asc, desc.
file_pathchaîne de caractèresNonFiltre par chemin de fichier exact.
upload_originchaîne de caractèresNonFiltre 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 :

ChampTypeDescription
identierL’identifiant unique du fichier source.
file_pathchaîne de caractèresLe chemin d’accès au fichier source dans le projet.
translation_pathchaîne de caractèresLe modèle d’emplacement où les fichiers traduits doivent être enregistrés.
additional_translation_filestableau[chaîne]Les chemins d’accès à tous les fichiers de sortie supplémentaires.
statuschaîne de caractèresL’état de traitement actuel du fichier source.
upload_originchaîne de caractèresComment le fichier a été téléversé (git, manual, api).
created_atchaîne de caractèresUn horodatage ISO 8601 indiquant la date de création du fichier source.
updated_atchaîne de caractèresUn horodatage ISO 8601 indiquant la dernière mise à jour du fichier source.
file_tagobjetInformations sur la balise de fichier.
file_tag.identierL’identifiant de la balise de fichier.
file_tag.namechaîne de caractèresLe nom de la balise de fichier.
download_urlchaîne de caractèresL’URL pour télécharger les traductions de ce fichier source.

Objet de pagination :

ChampTypeDescription
pageentierLe numéro de la page actuelle.
per_pageentierLe nombre d’éléments par page.
totalentierLe nombre total de fichiers source.
total_pagesentierLe nombre total de pages.
has_next_pagebooleanIndique s’il existe une page suivante disponible.
has_previous_pagebooleanIndique 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_strings

Paramètres

ParamètreTypeObligatoirePar défautDescription
file_pathchaîne de caractèresOuiLe chemin d’accès au fichier source dans le projet.
file_tag_namechaîne de caractèresNonLe nom de la balise de fichier. S’il n’est pas fourni, la balise par défaut du projet est utilisée.
pageentierNon1Le numéro de page pour la pagination (utilisé comme curseur). Doit être supérieur à 0.
qchaîne de caractèresNonLa 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
ChampTypeDescription
total_strings_countentierLe nombre total de chaînes traduisibles dans le fichier source.
translation_stringsarray[object]Le tableau d’objets de chaîne de traduction (paginé, max. 500 par page).
translation_strings[].sourcechaîne de caractèresLe texte source original à traduire.
translation_strings[].translationsobjetUn hachage de traductions où les clés sont des codes ISO de langue et les valeurs sont le texte traduit.
cursorentierLe 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ètreTypeObligatoireDescription
file_pathchaîne de caractèresOuiLe chemin d’accès où le fichier source doit être stocké dans le projet. Doit avoir une extension prise en charge.
output_file_pathchaîne de caractèresOuiLe modèle de chemin de sortie pour les fichiers traduits. Utilisez {{lang}} comme placeholder pour le code de langue.
translationsarray[object]NonLes 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_isochaîne de caractèresOuiLe 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[].filefileOuiLe fichier de traduction à téléverser.
additional_translation_filesarray[object]NonConfigurations 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[].typechaîne de caractèresOuiVoir les formats de fichiers pris en charge pour plus de détails.
additional_translation_files[].pathchaîne de caractèresOuiLe 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
ChampTypeDescription
source_file.identierL’identifiant unique du fichier source créé.
source_file.file_pathchaîne de caractèresLe chemin d’accès du fichier source dans le projet.
source_file.created_atchaîne de caractèresUn horodatage ISO 8601 indiquant la date de création du fichier source.
source_file.file_tag.identierL’identifiant de la balise de fichier.
source_file.file_tag.namechaîne de caractèresLe 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ètreTypeObligatoireDescription
filefileOuiLe 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_pathchaîne de caractèresOuiLe chemin d’accès au fichier source existant dans le projet qui doit être mis à jour.
file_tag_namechaîne de caractèresNonLe 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_urlchaîne de caractèresNonL’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
ChampTypeDescription
source_file.identierL’identifiant unique du fichier source traité.
source_file.file_pathchaîne de caractèresLe chemin d’accès du fichier source dans le projet.
source_file.created_atchaîne de caractèresUn horodatage ISO 8601 indiquant la date de création du fichier source.
source_file.file_tag.identierL’identifiant de la balise de fichier.
source_file.file_tag.namechaîne de caractèresLe 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

  1. Prérequis : Le fichier source doit déjà être créé via Créer le fichier source.
  2. Téléchargement du fichier : Le nouveau contenu est téléchargé et remplace le contenu du fichier existant.
  3. Traitement : Les nouvelles chaînes traduisibles sont extraites et traduites automatiquement.
  4. 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_status

Paramètres

ParamètreTypeObligatoireDescription
file_pathchaîne de caractèresOuiLe chemin d’accès au fichier source dans le projet.
file_tag_namechaîne de caractèresNonLe 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
ChampTypeDescription
translation_status.statuschaîne de caractèresL’état de traitement actuel du fichier source. Voir les valeurs d’état ci-dessous.
translation_status.completenessnombreLe 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 :

StatutDescription
pendingLe fichier source est en attente de traitement.
processingLa traduction est actuellement en cours.
completedToutes les traductions ont été effectuées.
failedLe 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ètreTypeObligatoireDescription
file_pathchaîne de caractèresOuiLe chemin d’accès au fichier source dans le projet.
file_tag_namechaîne de caractèresNonLe 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/zip
    • Content-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_files et ignoré.
  • Les fichiers avec des formats non pris en charge sont répertoriés sous unsupported_files et ignorés.
  • Les fichiers avec un contenu non valide sont également répertoriés sous unsupported_files et 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_url est fourni, une requête POST est 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ètreTypeObligatoireDescription
zip_filefileOuiUne archive ZIP contenant les fichiers source à télécharger. Il doit s’agir d’un fichier ZIP valide.
file_tag_namechaîne de caractèresNonNom 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_urlchaîne de caractèresNonL’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
ChampTypeDescription
successbooleanIndique si l’opération de chargement groupé a réussi.
file_tagobjetLes informations de la balise de fichier.
file_tag.identierL’identifiant de la balise de fichier.
file_tag.namechaîne de caractèresLe nom de la balise de fichier.
processed_filesarray[object]Un tableau de fichiers source qui ont été traités avec succès.
processed_files[].identierL’identifiant unique du fichier source créé.
processed_files[].file_pathchaîne de caractèresLe chemin d’accès du fichier source, en conservant la structure ZIP d’origine.
processed_files[].created_atchaîne de caractèresUn horodatage ISO 8601 indiquant la date de création du fichier source.
processed_files[].file_tagobjetLes informations de la balise de fichier.
processed_files[].file_tag.identierL’identifiant de la balise de fichier.
processed_files[].file_tag.namechaîne de caractèresLe nom de la balise de fichier.
unsupported_filestableau[chaîne]Un tableau de noms de fichiers qui ne sont pas dans un format pris en charge.
not_found_filestableau[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`);
Faire défiler vers le haut