PTC

Importer et gérer les fichiers de ressources via l’API

Utilisez cette API pour télécharger de nouveaux fichiers de ressources, remplacer les fichiers obsolètes, suivre la progression de la traduction et télécharger les traductions terminées.

Que vous gériez un fichier unique ou que vous automatisiez un flux de traduction continue, cette API vous donne un contrôle total sur le contenu que vous envoyez pour traduction et sur la manière dont vous recevez les traductions.

Comment l’API de PTC identifie et organise les fichiers sources

L’API de PTC utilise un système flexible basé sur des tags de fichiers (file tags) et des chemins de fichiers (file paths). Ces paramètres fonctionnent de concert pour garantir que chaque fichier que vous téléchargez, mettez à jour ou demandez est clairement défini et facile à gérer.

Étiquettes de fichiers

Les étiquettes de fichiers sont un moyen flexible de grouper et d’organiser les fichiers sources 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 étiquettes de fichiers peuvent indiquer :

  • Le contrôle de version : v1.0, beta, production
  • Les branches de fonctionnalités : user-auth, dashboard-redesign
  • Le contexte de l’application : mobile-app, admin-panel, marketing
  • L’équipe responsable : frontend-team, content-team
  • L’état du flux de travail : approved, pending-review, priority-high

Les noms d’étiquettes de fichiers sont facultatifs dans la plupart des opérations de l’API. Cependant, chaque fichier source possède toujours au moins une étiquette. Une étiquette de fichier par défaut est automatiquement créée et attribuée lors de la configuration d’un projet. Ce comportement par défaut permet de garder les projets organisés, même dans les configurations simples, tout en vous permettant de construire des structures d’étiquetage plus avancées si nécessaire.

Nom de l’étiquette + Chemin du fichier

Chaque fichier source est identifié de manière unique par la combinaison de son nom d’étiquette de fichier et de son chemin de fichier.

  • Si vous ne fournissez pas d’étiquette de fichier personnalisée lors du téléchargement ou du traitement d’un fichier, l’étiquette par défaut sera attribuée automatiquement.
  • Le nom de l’étiquette et le chemin d’un fichier définissent ensemble son identité. Cette combinaison garantit que chaque fichier est unique au sein de votre projet, même si différentes versions ou 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 concernés peuvent accepter des paramètres de requête tels que :

  • file_tag_name – L’étiquette associée au fichier
  • file_path – Le chemin vers le fichier

Ces paramètres vous permettent de localiser et de récupérer avec précision les fichiers corrects de votre projet.


Lister tous les fichiers sources du projet

Récupère la liste de tous les fichiers sources de votre projet, avec des options pour filtrer, trier et paginer les résultats. Cela est utile lorsque vous souhaitez parcourir vos fichiers, vérifier leur statut ou trouver des fichiers spécifiques en fonction d'une étiquette, d'un chemin ou d'une méthode d'importation.

Requête HTTP

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

Paramètres

Paramètre Type Requis Par défaut Description
page integer Non 1 Le numéro de page pour la pagination. Doit être supérieur à 0.
per_page integer Non 50 Le nombre d'éléments par page. Doit être supérieur à 0.
order_by string Non created_at Le champ utilisé pour le tri. Valeurs autorisées : id, created_at, updated_at.
sort string Non desc Le sens du tri. Valeurs autorisées : asc, desc.
file_path string Non Filtre par chemin de fichier exact.
upload_origin string Non Filtre selon le mode d'importation du fichier. Les valeurs autorisées incluent : git, manual, api.

Réponses

Réponse de succès

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

Objet Source File :

Champ Type Description
id integer L'identifiant unique du fichier source.
file_path string Le chemin vers le fichier source au sein du projet.
translation_path string Le modèle définissant l'emplacement où les fichiers traduits doivent être enregistrés.
additional_translation_files array[string] Les chemins pour tout fichier de sortie supplémentaire.
status string Le statut de traitement actuel du fichier source.
upload_origin string Le mode d'importation du fichier (git, manual, api).
created_at string Un horodatage ISO 8601 indiquant quand le fichier source a été initialement créé.
updated_at string Un horodatage ISO 8601 indiquant la date de la dernière mise à jour du fichier source.
file_tag object Informations sur le tag du fichier.
file_tag.id integer L'identifiant du tag de fichier.
file_tag.name string Le nom du tag de fichier.
download_url string L'URL pour télécharger les traductions de ce fichier source.

Objet Pagination :

Champ Type Description
page integer Le numéro de la page actuelle.
per_page integer Le nombre d'éléments par page.
total integer Le nombre total de fichiers sources.
total_pages integer Le nombre total de pages.
has_next_page boolean Indique si une page suivante est disponible.
has_previous_page boolean Indique si une page précédente est disponible.

Réponses d'erreur

Non autorisé
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Interdit
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}
Paramètres invalides
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 "Authorization: Bearer YOUR_API_TOKEN" \
  -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 "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Exemples de code

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

Obtenir les chaînes de traduction

Récupère toutes les chaînes traduisibles d’un fichier de ressources spécifique, ainsi que leurs traductions existantes dans toutes les langues cibles.

Cet endpoint est utile pour récupérer du contenu qui doit être traduit ou qui l’a déjà été. Le fichier de ressources 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ètre Type Requis Par défaut Description
file_path string Oui Le chemin vers le fichier de ressources au sein du projet.
file_tag_name string Non Le nom du tag de fichier. S’il n’est pas fourni, le tag par défaut du projet est utilisé.
page integer Non 1 Le numéro de page pour la pagination (utilisé comme curseur). Doit être supérieur à 0.
q string Non La requête de recherche pour filtrer les chaînes de traduction par leur texte source.

Réponses

Réponse de succès

200 OKapplication/json
{
  "total_strings_count": 1250,
  "translation_strings": [
    {
      "source": "Welcome to our application",
      "translations": {
        "es": "Bienvenido a nuestra aplicación",
        "fr": "Bienvenue dans notre application",
        "de": "Willkommen in unserer Anwendung"
      }
    },
    {
      "source": "Login",
      "translations": {
        "es": "Iniciar sesión",
        "fr": "Connexion",
        "de": "Anmelden"
      }
    }
  ],
  "cursor": 1
}
Schéma de réponse
Champ Type Description
total_strings_count integer Le nombre total de chaînes traduisibles dans le fichier de ressources.
translation_strings array[object] Le tableau d’objets de chaînes de traduction (paginé, max 500 par page).
translation_strings[].source string Le texte source original à traduire.
translation_strings[].translations object Un hash de traductions où les clés sont les codes ISO de langue et les valeurs sont le texte traduit.
cursor integer Le curseur de page actuel utilisé pour la pagination.

Réponses d’erreur

Fichier source non trouvé
404 Not Found
{
  "error": "Source file not found"
}
Non autorisé
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Interdit
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}
Paramètres invalides
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 "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Requête avec tag 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 "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

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 "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Exemples de code

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

Créer le fichier source

Enregistre un nouveau fichier source dans votre projet afin qu’il soit prêt pour la traduction.

Cet endpoint crée l’entrée du fichier et configure ses paramètres de traduction, mais il n’attache pas le contenu réel du fichier.

Après avoir créé le fichier, vous devrez utiliser l’endpoint de traitement du fichier source pour télécharger le contenu et lancer le processus de traduction.

Requête HTTP

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

Paramètres

Paramètre Type Requis Description
file_path string Oui Le chemin où le fichier source doit être stocké dans le projet. Doit avoir une extension prise en charge.
output_file_path string Oui Le modèle de chemin de sortie pour les fichiers traduits. Utilisez {{lang}} comme espace réservé pour le code de langue.
translations array[object] Non Les fichiers de traduction préexistants à télécharger en même temps que 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 tout le contexte de votre projet et traduire à partir de zéro.
translations[].target_language_iso string Oui Le code ISO de la langue cible pour cette traduction. Vous trouverez la liste complète des langues prises en charge et leurs codes ISO dans l’endpoint de liste de toutes les langues cibles.
translations[].file file Oui Le fichier de traduction à télécharger.
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, reportez-vous à l’endpoint de liste des formats de fichiers pris en charge. Pour les formats non pris en charge, ce champ sera ignoré.
additional_translation_files[].type string Oui Voir les formats de fichiers pris en charge pour plus de détails.
additional_translation_files[].path string Oui Le modèle de chemin pour le fichier.

Réponses

Réponse de succès

201 Createdapplication/json
{
  "source_file": {
    "id": 123,
    "file_path": "src/locales/en.json",
    "created_at": "2024-01-15T10:30:00.000Z",
    "file_tag": {
      "id": 456,
      "name": "frontend"
    }
  }
}
Schéma de réponse
Champ Type Description
source_file.id integer L’identifiant unique du fichier source créé.
source_file.file_path string Le chemin du fichier source au sein du projet.
source_file.created_at string Un horodatage ISO 8601 indiquant quand le fichier source a été initialement créé.
source_file.file_tag.id integer L’identifiant du tag de fichier.
source_file.file_tag.name string Le nom du tag de fichier.

Réponses d’erreur

Échec de la validation
422 Unprocessable Entity
{
  "success": false,
  "error": "Source file creation failed"
}
Non autorisé
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Interdit
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

Exemples de requêtes

Création de base d’un fichier source :

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

Requête avec URL de rappel (callback) :

curl -X POST "https://app.ptc.wpml.org/api/v1/source_files" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -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 traductions préexistantes :

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

Requête avec fichiers de sortie supplémentaires :

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

Exemples de code

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

Traiter le fichier source

Envoie le contenu vers un fichier source existant et lance le processus de traduction.

Cet endpoint remplace le contenu actuel du fichier, met à jour les chaînes traduisibles stockées et démarre la traduction automatique.

Pour utiliser cet endpoint, le fichier source doit déjà exister dans le projet. Si vous ne l'avez pas encore créé, consultez la section Créer le fichier source.

Requête HTTP

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

Paramètres

Paramètre Type Requis 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 du JSON valide.
file_path string Oui Le chemin vers le fichier source existant dans le projet qui doit être mis à jour.
file_tag_name string Non Le nom du tag de fichier associé au fichier source. S'il n'est pas fourni, le tag de fichier par défaut du projet est utilisé.
callback_url string Non L'URL qui reçoit les notifications de webhook lorsque le traitement du fichier est terminé.

Réponses

Réponse de succès

200 OKapplication/json
{
  "source_file": {
    "id": 123,
    "file_path": "src/locales/en.json",
    "created_at": "2024-01-15T10:30:00.000Z",
    "file_tag": {
      "id": 456,
      "name": "frontend"
    }
  }
}
Schéma de réponse
Champ Type Description
source_file.id integer L'identifiant unique du fichier source traité.
source_file.file_path string Le chemin du fichier source au sein du projet.
source_file.created_at string Un horodatage ISO 8601 indiquant quand le fichier source a été initialement créé.
source_file.file_tag.id integer L'identifiant du tag de fichier.
source_file.file_tag.name string Le nom du tag de fichier.

Réponses d'erreur

Fichier source non trouvé
422 Unprocessable Entity
{
  "errors": {
    "file": ["File format is invalid or not supported"]
  }
}
Non autorisé
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Interdit
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

Flux de travail

  1. Prérequis : Le fichier source doit déjà avoir été 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 (Callback) : Une notification de webhook optionnelle est envoyée à la fin du traitement.

Rappel de Webhook (Callback)

Lorsqu'une callback_url est fournie, PTC enverra une requête POST à cette URL une fois le traitement 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 PUT "https://app.ptc.wpml.org/api/v1/source_files/process" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@updated_translations.json" \
  -F "file_path=src/locales/en.json" \
  -F "file_tag_name=frontend"

Requête avec URL de rappel :

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

Exemples de code

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

Formats de fichiers pris en charge

L'endpoint 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 l'endpoint Lister les formats de fichiers pris en charge pour obtenir la liste complète des formats supportés.


Obtenir l’état de la traduction

Récupère la progression actuelle de la traduction pour un fichier source spécifique, y compris le niveau d’achèvement et son état de traitement global.

Ceci est utile pour :

  • Le suivi de la progression – Suivre l’avancement de la traduction pour les travaux de longue durée
  • Les mises à jour de l’interface utilisateur – Afficher les pourcentages d’achèvement dans votre application
  • L’intégration au flux de travail – Déclencher des 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ètre Type Requis Description
file_path string Oui Le chemin vers le fichier source au sein du projet.
file_tag_name string Non Le nom de l’étiquette du fichier. S’il n’est pas fourni, l’étiquette de fichier par défaut du projet est utilisée.

Réponses

Réponse de succès

200 OKapplication/json
{
  "translation_status": {
    "status": "completed",
    "completeness": 100
  }
}
Schéma de réponse
Champ Type Description
translation_status.status string L’état de traitement actuel du fichier source. Voir les valeurs d’état ci-dessous.
translation_status.completeness number Le pourcentage de chaînes traduites (0–100). Calculé comme suit : (completed_translatable_strings / total_translatable_strings) × 100.

Valeurs d’état

Le champ status peut contenir les valeurs suivantes :

État Description
pending Le fichier source est en attente de traitement.
processing La traduction est actuellement en cours.
completed Toutes les traductions ont été terminées.
failed Le processus de traduction a rencontré des erreurs.

Réponses d’erreur

Fichier source non trouvé
404 Not Found
{
  "error": "Source file not found"
}
Non autorisé
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Interdit
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}
Paramètres invalides
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 "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Requête avec étiquette 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 "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Exemples de code

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

Télécharger toutes les traductions

Télécharge tous les fichiers traduits pour un fichier source spécifique sous forme d'archive ZIP.

Cet endpoint 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 Not Found.

Requête HTTP

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

Paramètres

Paramètre Type Requis Description
file_path string Oui Le chemin vers le fichier source au sein du projet.
file_tag_name string Non Le nom du tag de fichier. S'il n'est pas fourni, le tag de fichier par défaut du projet est utilisé. 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

200 OKapplication/zip202 AcceptedRetry-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 une courte attente entre le téléchargement d'un fichier source et la disponibilité des traductions pour le téléchargement.

Lorsque cela se produit, attendez le nombre de secondes spécifié dans Retry-After.

Réponses d'erreur

Fichier source non trouvé
404 Not Found
{
  "error": "Source file not found"
}
Aucune traduction disponible
404 Not Found
{
  "error": "No translations are available for this source file"
}
Non autorisé
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Interdit
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}
Paramètres invalides
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 "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -o translations.zip

Requête avec tag 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 "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -o frontend-translations.zip

Exemples de code

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

Télécharger des fichiers sources en masse

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 par lot de Process the Source File, conçue pour accélérer les mises à jour à grande échelle.

Informations complé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 dont le format n’est pas pris en charge sont répertoriés sous unsupported_files et ignorés.
  • Les fichiers dont le contenu est invalide sont également répertoriés sous unsupported_files et ignorés.
  • Le traitement des archives volumineuses peut prendre plus de temps. Les fichiers sont traités un par un pour gérer les ressources ; il est donc préférable de diviser les téléchargements très volumineux (plus de 100 fichiers) en lots plus petits. Tous les fichiers de l’archive sont configurés pour être traduits automatiquement.
  • Le fichier ZIP téléchargé doit être valide et lisible. Tous les fichiers qu’il contient doivent être dans un format pris en charge. Les noms de fichiers ne doivent pas inclure de caractères spéciaux susceptibles de causer des problèmes de chemin.
  • Si une callback_url est fournie, 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ètre Type Requis Description
zip_file file Oui Une archive ZIP contenant les fichiers sources à télécharger. Il doit s’agir d’un fichier ZIP valide.
file_tag_name string Non Le nom du tag de fichier à associer à tous les fichiers sources de l’archive. S’il n’est pas spécifié, le tag de fichier par défaut du projet est utilisé. Chaque fichier source est identifié de manière unique par la combinaison de file_path et file_tag_name.
callback_url string Non L’URL qui reçoit les notifications de webhook lors du traitement de chaque fichier.

Structure attendue du fichier ZIP

Le fichier ZIP peut contenir des fichiers sources dans n’importe quelle structure de répertoires. La structure des répertoires est préservé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

200 OKapplication/json
{
  "success": true,
  "file_tag": {
      "id": 456,
      "name": "backend"
  },
  "processed_files": [
    {
      "id": 123,
      "file_path": "locales/messages-en.po",
      "created_at": "2024-01-15T10:30:00.000Z",
      "file_tag": {
        "id": 456,
        "name": "backend"
      }
    },
    {
      "id": 124,
      "file_path": "locales/validation-en.po",
      "created_at": "2024-01-15T10:30:05.000Z",
      "file_tag": {
        "id": 456,
        "name": "backend"
      }
    }
  ],
  "unsupported_files": [
    "readme.txt",
    "config.ini"
  ],
  "not_found_files": ["frontend/not-found-en.json"]
}
Schéma de réponse
Champ Type Description
success boolean Indique si l’opération de téléchargement en masse a réussi.
file_tag object Les informations sur le tag de fichier.
file_tag.id integer L’identifiant du tag de fichier.
file_tag.name string Le nom du tag de fichier.
processed_files array[object] Un tableau des fichiers sources qui ont été traités avec succès.
processed_files[].id integer L’identifiant unique du fichier source créé.
processed_files[].file_path string Le chemin du fichier source, préservant la structure originale du ZIP.
processed_files[].created_at string Un horodatage ISO 8601 indiquant quand le fichier source a été créé.
processed_files[].file_tag object Les informations sur le tag de fichier.
processed_files[].file_tag.id integer L’identifiant du tag de fichier.
processed_files[].file_tag.name string Le nom du tag de fichier.
unsupported_files array[string] Un tableau de noms de fichiers qui ne sont pas dans un format pris en charge.
not_found_files array[string] Un tableau de fichiers pris en charge qui ne correspondaient à aucun fichier source existant et qui ont été ignorés.

Réponses d’erreur

Fichier ZIP invalide

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

Échec du traitement

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

Non autorisé

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

Interdit

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

Rappel de Webhook (Callback)

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": "locales/messages-en.po"
}

Exemples de requêtes

Téléchargement en masse basique :

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

Requête avec URL de rappel :

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

Exemples de code

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

Trouver les formats de fichiers pris en charge et les langues cibles via l’API →