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 les fichiers obsolètes, suivre la progression de la traduction et télécharger les traductions terminées.

Que vous gériez un seul fichier ou 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 des étiquettes de fichier et des chemins de fichier. Ces paramètres fonctionnent ensemble pour s'assurer 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és : 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 d'étiquettes de fichier sont facultatifs dans la plupart des opérations d'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 entier Non 1 Le numéro de page pour la pagination. Doit être supérieur à 0.
per_page entier Non 50 Le nombre d'éléments par page. Doit être supérieur à 0.
order_by chaîne Non created_at Le champ par lequel trier. Valeurs autorisées : id, created_at, updated_at.
sort chaîne Non desc La direction du tri. Valeurs autorisées : asc, desc.
file_path chaîne Non Filtre par chemin de fichier exact.
upload_origin chaîne Non Filtre selon 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

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 de fichier source :

Champ Type Description
id entier L'identifiant unique du fichier source.
file_path chaîne Le chemin vers le fichier source au sein du projet.
translation_path chaîne Le modèle indiquant où les fichiers traduits doivent être enregistrés.
additional_translation_files tableau[chaîne] Les chemins pour tous les fichiers de sortie supplémentaires.
status chaîne Le statut de traitement actuel du fichier source.
upload_origin chaîne La façon dont le fichier a été téléversé (git, manual, api).
created_at chaîne Un horodatage ISO 8601 indiquant quand le fichier source a été initialement créé.
updated_at chaîne Un horodatage ISO 8601 indiquant quand le fichier source a été mis à jour pour la dernière fois.
file_tag objet Informations sur l'étiquette de fichier.
file_tag.id entier L'identifiant de l'étiquette de fichier.
file_tag.name chaîne Le nom de l'étiquette de fichier.
download_url chaîne L'URL pour télécharger les traductions de ce fichier source.

Objet de pagination :

Champ Type Description
page entier Le numéro de page actuel.
per_page entier Le nombre d'éléments par page.
total entier Le nombre total de fichiers sources.
total_pages entier Le nombre total de pages.
has_next_page booléen Indique s'il y a une page suivante disponible.
has_previous_page booléen 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"

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 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 chaîne Oui Le chemin vers le fichier source au sein du projet.
file_tag_name chaîne 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 entier Non 1 Le numéro de page pour la pagination (utilisé comme curseur). Doit être supérieur à 0.
q chaîne 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 entier Le nombre total de chaînes traduisibles dans le fichier source.
translation_strings tableau[objet] Le tableau d'objets de chaînes de traduction (paginé, max 500 par page).
translation_strings[].source chaîne Le texte source original à traduire.
translation_strings[].translations objet Un hash de traductions où les clés sont les codes ISO des langues et les valeurs sont le texte traduit.
cursor entier Le curseur de page actuel utilisé pour la pagination.

Réponses d'erreur

Fichier source introuvable
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 afin qu'il soit prêt à traduire.

Ce point de terminaison crée l'entrée du fichier et configure ses paramètres de traduction, mais ne joint 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éverser 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 chaîne Oui Le chemin où le fichier source doit être stocké dans le projet. Doit avoir une extension prise en charge.
output_file_path chaîne Oui Le modèle de chemin de sortie pour les fichiers traduits. Utilisez {{lang}} comme espace réservé pour le code de langue.
translations tableau[objet] Non Les fichiers de traductions préexistantes à téléverser 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 que fournir des traductions existantes n'est pas recommandé, car PTC produit de meilleurs résultats lorsqu'il peut utiliser le contexte complet de votre projet et traduire de zéro.
translations[].target_language_iso chaîne Oui Le code ISO de la langue cible pour cette traduction. Vous pouvez trouver la liste complète des langues prises en charge et de leurs codes ISO dans le point de terminaison Lister toutes les langues cibles.
translations[].file fichier Oui Le fichier de traduction à téléverser.
additional_translation_files tableau[objet] 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 le point de terminaison Lister les formats de fichiers pris en charge. Pour les formats non pris en charge, ce champ sera ignoré.
additional_translation_files[].type chaîne Oui Voir les formats de fichiers pris en charge pour plus de détails.
additional_translation_files[].path chaîne 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 entier L'identifiant unique du fichier source créé.
source_file.file_path chaîne Le chemin du fichier source au sein du projet.
source_file.created_at chaîne Un horodatage ISO 8601 indiquant quand le fichier source a été initialement créé.
source_file.file_tag.id entier L'identifiant de l'étiquette de fichier.
source_file.file_tag.name chaîne 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 fichier source de base :

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 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[][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.

Ce point de terminaison remplace le contenu actuel du fichier, met à jour les chaînes traduisibles stockées et lance la traduction automatique.

Pour utiliser ce point de terminaison, le fichier source doit déjà exister dans le projet. Si vous ne l'avez pas encore créé, consultez Créer le fichier source.

Requête HTTP

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

Paramètres

Paramètre Type Requis Description
file fichier 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 du JSON valide.
file_path chaîne Oui Le chemin vers le fichier source existant dans le projet qui doit être mis à jour.
file_tag_name chaîne 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 chaîne 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 entier L'identifiant unique du fichier source traité.
source_file.file_path chaîne Le chemin du fichier source au sein du projet.
source_file.created_at chaîne Un horodatage ISO 8601 indiquant quand le fichier source a été initialement créé.
source_file.file_tag.id entier L'identifiant de l'étiquette de fichier.
source_file.file_tag.name chaîne Le nom de l'étiquette de fichier.

Réponses d'erreur

Fichier source introuvable
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à être créé via Créer le fichier source.
  2. Téléversement du 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 se termine.

Callback 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 de traduction actuelle pour un fichier source spécifique, y compris le pourcentage d'achèvement et son statut de traitement global.

Cela est utile pour :

  • Le suivi de la progression – Suivre la progression de la traduction pour les tâches longues
  • Les mises à jour de l'interface utilisateur – Afficher les pourcentages d'achèvement dans votre application
  • L'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 chaîne Oui Le chemin vers le fichier source au sein du projet.
file_tag_name chaîne 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 chaîne Le statut de traitement actuel du fichier source. Voir les valeurs de statut ci-dessous.
translation_status.completeness nombre Le pourcentage de chaînes traduites (0–100). Calculé comme (completed_translatable_strings / total_translatable_strings) × 100.

Valeurs de statut

Le champ status peut contenir les valeurs suivantes :

Statut Description
pending Le fichier source est en attente de traitement.
processing La traduction est actuellement en cours.
completed Toutes les traductions sont 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 chaîne Oui Le chemin vers le fichier source au sein du projet.
file_tag_name chaîne 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 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 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 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 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 listés sous unsupported_files et ignorés.
  • Les fichiers avec un contenu invalide sont également listés sous unsupported_files et ignorés.
  • Les grandes archives 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éversements (plus de 100 fichiers) en lots plus petits. Tous les fichiers de l'archive sont configurés pour être traduits automatiquement.
  • Le ZIP téléversé 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.
  • 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 fichier Oui Une archive ZIP contenant les fichiers sources à téléverser. Il doit s'agir d'un fichier ZIP valide.
file_tag_name chaîne Non Le nom de l'étiquette de fichier à associer à tous les fichiers sources de 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 chaîne Non L'URL qui reçoit les notifications webhook lorsque chaque fichier est traité.

Structure de fichier ZIP attendue

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 booléen Indique si l'opération de téléversement en masse a réussi.
file_tag objet Informations sur l'étiquette de fichier.
file_tag.id entier L'identifiant de l'étiquette de fichier.
file_tag.name chaîne Le nom de l'étiquette de fichier.
processed_files tableau[objet] Un tableau de fichiers sources qui ont été traités avec succès.
processed_files[].id entier L'identifiant unique du fichier source créé.
processed_files[].file_path chaîne Le chemin du fichier source, en conservant la structure ZIP d'origine.
processed_files[].created_at chaîne Un horodatage ISO 8601 indiquant quand le fichier source a été créé.
processed_files[].file_tag objet Informations sur l'étiquette de fichier.
processed_files[].file_tag.id entier L'identifiant de l'étiquette de fichier.
processed_files[].file_tag.name chaîne Le nom de l'étiquette de fichier.
unsupported_files tableau[chaîne] Un tableau de noms de fichiers qui ne sont pas dans un format pris en charge.
not_found_files tableau[chaîne] Un tableau de fichiers pris en charge qui ne correspondaient à aucun fichier source existant et ont été ignorés.

Réponses d'erreur

Fichier ZIP 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 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 et les langues cibles pris en charge via l'API →