PTC

Téléverser et gérer les fichiers sources via l'API

Utilisez cette API pour téléverser de nouveaux fichiers sources, remplacer ceux qui sont obsolètes, suivre la progression des traductions et télécharger les traductions terminées.

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 en traduction et sur la façon dont vous recevez les traductions.

Comment l'API PTC identifie et organise les fichiers sources

L'API PTC utilise un système flexible basé sur les étiquettes 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.

Étiquettes de fichier

Les étiquettes de fichier constituent un moyen flexible de regrouper 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 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
  • Équipe responsable : frontend-team, content-team
  • État du flux de travail : approved, pending-review, priority-high

Les noms d'étiquette de fichier 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 des configurations simples, tout en vous permettant de créer des structures d'étiquetage plus avancées si nécessaire.

Nom d'étiquette de fichier + Chemin de 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éversement ou du traitement d'un fichier, l'étiquette par défaut sera attribuée automatiquement.
  • Le nom d'étiquette + 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 associé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 précisément les bons fichiers de votre projet.


Lister tous les fichiers sources du projet

Liste 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 de l'étiquette, 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è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 sur lequel trier. Valeurs autorisées : id, created_at, updated_at.
sort string Non desc La direction du tri. Valeurs autorisées : asc, desc.
file_path string Non – Filtre par chemin de fichier exact.
upload_origin string Non – Filtre selon la méthode de téléversement 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 fichier source :

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 indiquant où les fichiers traduits doivent être enregistrés.
additional_translation_files array[string] Les chemins pour d'éventuels fichiers de sortie supplémentaires.
status string Le statut de traitement actuel du fichier source.
upload_origin string La méthode de téléversement du fichier (git, manual, api).
created_at string Un horodatage ISO 8601 indiquant quand le fichier source a été créé initialement.
updated_at string Un horodatage ISO 8601 indiquant quand le fichier source a été mis à jour pour la dernière fois.
file_tag object Des informations sur l'étiquette de fichier.
file_tag.id integer L'identifiant de l'étiquette de fichier.
file_tag.name string Le nom de l'étiquette de fichier.
download_url string L'URL pour télécharger les traductions pour ce fichier source.

Objet de 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 s'il y a une page suivante disponible.
has_previous_page boolean Indique s'il y a une page précédente 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"

Get Translation Strings

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 récupérer du contenu qui doit être traduit ou qui a déjà été traduit. 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ètre Type Requis Par défaut 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 de fichier. S'il n'est pas fourni, l'étiquette par défaut du projet est utilisée.
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 source.
translation_strings array[object] Le tableau d'objets de chaîne de traduction (paginé, maximum 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 des langues et les valeurs sont le texte traduit.
cursor integer Le curseur de la page actuelle utilisé pour la pagination.

Réponses d'erreur

Fichier source introuvable
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"

Une requête avec étiquette 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"

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 "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 pour qu'il soit prêt pour la traduction.

Cet endpoint crée l'entrée du fichier et met en place sa configuration de traduction, mais n'y joint pas le contenu réel du fichier.

Après avoir créé le fichier, vous devrez utiliser l'endpoint Traiter le fichier source pour téléverser 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 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.
file_tag_name string Non Le nom de l'étiquette de fichier sous laquelle enregistrer le fichier source. S'il n'est pas fourni, l'étiquette de fichier par défaut du projet est utilisée.
translations array[object] Non Les fichiers de traductions préexistantes à 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 string 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 l'endpoint 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 les fichiers de sortie supplémentaires, consultez l'endpoint Lister les 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 de l'étiquette de fichier.
source_file.file_tag.name string Le nom de l'étiquette 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"

L'endpoint de création n'accepte pas callback_url. L'enregistrement d'un fichier source ne lance aucune traduction, il n'y a donc rien qu'un callback puisse annoncer — passez-le plutôt à Traiter le fichier source ou à Téléverser des fichiers sources en masse, qui sont les appels initiant le travail.

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[][type]=mo" \
  -F "additional_translation_files[][path]=locales/{{lang}}/messages.mo" \
  -F "additional_translation_files[][type]=json" \
  -F "additional_translation_files[][path]=locales/{{lang}}/messages.json"

Exemples de code

  • JavaScript (FormData)
  • Python (requests)
  • PHP (cURL)
  • Node.js (axios)
  • Corps de la requête de 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

Téléverse du 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 lance 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 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éverser. 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éversé doit être un JSON valide.
file_path string Oui Le chemin d'accès au fichier source existant dans le projet qui doit être mis à jour.
file_tag_name string Non Le nom de l'étiquette de fichier associée au fichier source. S'il n'est pas fourni, l'étiquette de fichier par défaut du projet est utilisée.
callback_url string Non L'URL qui reçoit les notifications 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 d'accès 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 de l'étiquette de fichier.
source_file.file_tag.name string Le nom de l'étiquette de fichier.

Réponses d'erreur

Format de fichier non pris en charge ou invalide

L'endpoint de traitement remplace le contenu du fichier par ce que vous téléversez, il n'y a donc aucune recherche susceptible d'échouer — cet endpoint ne comporte aucun cas « non trouvé ». Le seul rejet qu'il renvoie concerne la vérification du contenu du fichier téléversé.

422 Unprocessable Entity
{
  "success": false,
  "message": "Unprocessable Entity",
  "code": 422,
  "errors": [9001]
}

errors est un tableau de codes numériques, et non un objet dont les clés sont des champs. 9001 signifie que le contenu n'a pas pu être analysé selon le format indiqué par son extension. Certains rejets ajoutent un objet additional_info à côté avec les détails.

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éversement de fichier : Le nouveau contenu est téléversé et remplace le contenu du fichier existant.
  3. Traitement : Les nouvelles chaînes traduisibles sont extraites et traduites automatiquement.
  4. Callback : Une notification webhook facultative est envoyée lorsque le traitement est terminé.

Callback de webhook

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 callback :

{
  "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 callback :

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

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éversement 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 le statut de traduction

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

Ceci est utile pour :

  • Surveillance de la progression – Suivre la progression de la traduction pour les tâches de longue durée
  • Mises à jour de l'interface utilisateur – Afficher les pourcentages d'achèvement dans votre application
  • Intégration du 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 dans le projet.
file_tag_name string Non Le nom de l'étiquette de 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 Le statut de traitement actuel du fichier source. Voir les valeurs de statut ci-dessous.
translation_status.completeness number Le pourcentage de chaînes traduites (0–100). Calculé selon (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é terminées.
failed Le processus de traduction a rencontré des erreurs.

Réponses d'erreur

Fichier source introuvable
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.

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 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 dans le projet.
file_tag_name string Non Le nom de l'étiquette de fichier. S'il n'est pas fourni, l'étiquette 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 de 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éversement d'un fichier source et la disponibilité des traductions au téléchargement.

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

Réponses d'erreur

Fichier source introuvable
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 étiquette 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éverser des fichiers sources en masse

Téléverse 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 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 de nouveau déclenchées.
  • 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.
  • Les grandes archives peuvent prendre plus de temps à être traitées. 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éversements (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éversé 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 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ètre Type Requis Description
zip_file file Oui Une archive ZIP contenant les fichiers sources à téléverser. Il doit s'agir d'un fichier ZIP valide.
file_tag_name string Non Le nom de l'étiquette de fichier à associer à tous les fichiers sources dans l'archive. S'il n'est pas spécifié, l'étiquette 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 string Non L'URL qui reçoit les notifications de webhook lorsque chaque fichier est traité.

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

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éversement en masse a réussi.
file_tag object Les informations de l'étiquette de fichier.
file_tag.id integer L'identifiant de l'étiquette de fichier.
file_tag.name string Le nom de l'étiquette 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, conservant la structure ZIP d'origine.
processed_files[].created_at string Un horodatage ISO 8601 indiquant quand le fichier source a été créé.
processed_files[].file_tag object Les informations de l'étiquette de fichier.
processed_files[].file_tag.id integer L'identifiant de l'étiquette de fichier.
processed_files[].file_tag.name string Le nom de l'étiquette 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 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."
}

Callback 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 callback (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éversement en masse de base :

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 callback :

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 →