PTC

Demander et récupérer des traductions via l'API

Utilisez cette API pour envoyer du contenu à traduire, suivre sa progression et récupérer les traductions dans toutes les langues cibles.

Cette API accepte le contenu structuré en JSON, en préservant la structure et les clés d'origine. Elle traduit uniquement les valeurs textuelles, laissant les nombres, les booléens, les valeurs nulles et les autres valeurs non textuelles inchangés.

Create Content Translations

Crée une nouvelle tâche de traduction à partir de données structurées en JSON.

Le point de terminaison d'API préserve la hiérarchie d'origine des clés et des tableaux de votre contenu, en traduisant uniquement les valeurs textuelles tout en laissant les nombres, les booléens, les valeurs nulles et les autres valeurs non textuelles inchangés.

Il est particulièrement utile pour :

  • Gestion de contenu – Localiser du contenu dynamique structuré en JSON
  • Fichiers de configuration – Traduire des chaînes d'interface utilisateur dans les données de configuration
  • Réponses d'API – Traduire des charges utiles de réponse structurées
  • Documentation – Localiser du contenu d'aide ou des guides hiérarchiques

Pour une implémentation Rails complète de ce flux de travail, consultez la traduction de contenu dynamique dans Rails à l'aide de l'API PTC.

Requête HTTP

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

Paramètres

Paramètre Type Requis Description
data object Oui Les données structurées en JSON à traduire. Elles peuvent inclure des objets imbriqués, des tableaux et des valeurs de chaîne.
name string Non Un nom lisible pour la tâche de traduction. S'il est omis, un nom est généré automatiquement.
callback_url string Non L'URL qui reçoit les notifications webhook lorsque la traduction est terminée.
target_languages array[string] Non Le tableau des codes ISO pour les langues cibles. S'il est omis, des traductions sont créées pour toutes les langues configurées pour le projet. Consultez l'API Langues cibles disponibles pour plus d'informations.

Exemple de corps de requête

{
  "data": {
    "app": {
      "title": "My Application",
      "navigation": {
        "home": "Home",
        "about": "About Us",
        "contact": "Contact"
      },
      "buttons": {
        "save": "Save",
        "cancel": "Cancel",
        "submit": "Submit"
      },
      "messages": {
        "welcome": "Welcome to our platform",
        "error": "An error occurred"
      }
    },
    "version": "1.0.0",
    "settings": {
      "theme": "dark",
      "notifications": true
    }
  },
  "name": "App UI Translations",
  "callback_url": "https://your-app.com/webhooks/translation-complete",
  "target_languages": ["es", "fr", "de"]
}

Réponses

Réponse de succès

201 Createdapplication/json
{
  "id": 123,
  "name": "App UI Translations",
  "status": "queued",
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z"
}

Schéma de réponse

Champ Type Description
id number L'identifiant unique de la tâche de traduction de contenu.
name string Le nom de la tâche (généré automatiquement s'il n'est pas fourni).
status string Le statut actuel de la tâche (queued, processing, completed).
created_at string L'horodatage ISO 8601 indiquant quand la tâche a été créée.
updated_at string L'horodatage ISO 8601 indiquant la dernière mise à jour de la tâche.

Réponses d'erreur

Données JSON invalides
422 Unprocessable Entity
{
  "errors": {
    "data": ["Data must be a valid JSON object"]
  }
}
Langues cibles invalides
422 Unprocessable Entity
{
  "errors": {
    "target_languages": ["Language codes [zh, xx] are not configured for this project"]
  }
}
Non autorisé
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Interdit
403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

Traitement des données JSON

Lors de l'utilisation de données structurées en JSON, PTC traite les données comme suit :

  • La structure est préservée – La hiérarchie d'origine des clés et de l'imbrication reste inchangée
  • Seules les chaînes sont traduites – Les nombres, les booléens, les tableaux et les valeurs nulles sont conservés tels quels
  • Traduction basée sur le chemin – Chaque chaîne traduisible est identifiée par son chemin JSON
  • Prise en charge de l'imbrication – Fonctionne avec des objets et des tableaux profondément imbriqués
  • Gestion des types de données mixtes – Les valeurs non textuelles sont préservées sans modification

Exemple de transformation de données

Entrée :

{
  "user": {
    "name": "Welcome User",
    "settings": {
      "theme": "Choose Theme",
      "count": 5,
      "enabled": true
    }
  }
}

Résultat du traitement :

  • user.name : « Welcome User » → Est traduit
  • user.settings.theme : « Choose Theme » → Est traduit
  • user.settings.count: 5 → Reste inchangé
  • user.settings.enabled: true → Reste inchangé

Flux de travail de traduction

  1. Validation : La structure JSON et les langues cibles sont vérifiées
  2. Préparation du fichier source : Le JSON est converti dans un format source interne
  3. Réutilisation des chaînes via la mémoire de traduction : Toutes les chaînes traduisibles sont extraites et stockées dans la mémoire de traduction de votre projet afin que les traductions précédentes puissent être réutilisées
  4. Mise en file d'attente de la tâche : Une tâche est mise en file d'attente pour chaque langue cible
  5. Traitement : La traduction automatique s'exécute sur les chaînes extraites
  6. Callback (facultatif) : Un webhook est envoyé lorsque toutes les traductions sont terminées, si callback_url est fourni

Callback du webhook

Lorsqu'une callback_url est fournie, une requête POST est envoyée lorsque la tâche est terminée.

Corps de la requête de callback :

{
  "id": 1,
  "status": "completed",
  "translations_url": "https://app.ptc.wpml.org/api/v1/content_translation/1"
}

Types de données pris en charge

Type JSON Comportement de traduction
string Traduit dans les langues cibles
number Conservé tel quel
boolean Conservé tel quel
null Conservé tel quel
array Traité de manière récursive
object Traité de manière récursive

Exemples de requêtes

Traduction JSON de base :

curl -X POST "https://app.ptc.wpml.org/api/v1/content_translation" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "welcome": "Welcome",
      "buttons": {
        "save": "Save",
        "cancel": "Cancel"
      }
    },
    "name": "UI Labels"
  }'

Avec des langues cibles spécifiques :

curl -X POST "https://app.ptc.wpml.org/api/v1/content_translation" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "title": "Product Catalog",
      "categories": {
        "electronics": "Electronics",
        "clothing": "Clothing"
      }
    },
    "target_languages": ["es", "fr"],
    "callback_url": "https://myapp.com/webhook"
  }'

Exemples de code

curl -X POST "https://app.ptc.wpml.org/api/v1/content_translation" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data":{"app":{"title":"My Application","navigation":{"home":"Home","about":"About Us"}}},"name":"App Translations","target_languages":["es","fr","de"],"callback_url":"https://your-app.com/webhooks/complete"}'

# The response includes the job "id". Poll its status (the create response
# carries a "status" field as well, but it is usually null until the run
# starts, and stays "in_progress" until done):
curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/CONTENT_TRANSLATION_ID/status" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Get Content Translations

Récupère le contenu d'origine et toutes les versions traduites pour une tâche de traduction de contenu spécifique.

La réponse préserve votre structure d'entrée : elle renvoie un objet source plus un objet par langue cible (indexé par le code de langue tel que es, fr, de).

Requête HTTP

GET https://app.ptc.wpml.org/api/v1/content_translation/{id}

Paramètres de chemin

Paramètre Type Requis Description
id integer Oui L'identifiant unique de la tâche de traduction de contenu à récupérer.

Réponses

Réponse de succès

200 OKapplication/json
{
  "source": {
    "app": {
      "title": "My Application",
      "navigation": {
        "home": "Home",
        "about": "About",
        "contact": "Contact"
      },
      "buttons": {
        "save": "Save",
        "cancel": "Cancel"
      }
    }
  },
  "es": {
    "app": {
      "title": "Mi Aplicación",
      "navigation": {
        "home": "Inicio",
        "about": "Acerca de",
        "contact": "Contacto"
      },
      "buttons": {
        "save": "Guardar",
        "cancel": "Cancelar"
      }
    }
  },
  "fr": {
    "app": {
      "title": "Mon Application",
      "navigation": {
        "home": "Accueil",
        "about": "À propos",
        "contact": "Contact"
      },
      "buttons": {
        "save": "Enregistrer",
        "cancel": "Annuler"
      }
    }
  }
}

Schéma de réponse

Champ Type Description
source object Le contenu source d'origine dans la même structure imbriquée que celle soumise.
{language_code} object Le contenu traduit pour chaque langue cible, indexé par son code ISO (par exemple es, fr, de), avec la même structure que la source. Pour plus d'informations, consultez l'API Langues cibles disponibles.

Réponses d'erreur

Traduction de contenu introuvable
404 Not Found
{
  "error": "Content translation not found"
}
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

Requête de base :

curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/123" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Exemples de code

curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/123" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Obtenir le statut de traduction de contenu

Récupère le statut actuel d'une tâche de traduction de contenu spécifique.

La réponse reflète la progression globale et indique si la traduction est en file d'attente, en cours, terminée ou a échoué.

Requête HTTP

GET https://app.ptc.wpml.org/api/v1/content_translation/{id}/status

Paramètres de chemin

Paramètre Type Requis Description
id integer Oui L'identifiant unique de la tâche de traduction de contenu à vérifier.

Réponses

Réponse de succès

200 OKapplication/json
{
  "status": "completed",
  "completeness": 100
}
Schéma de réponse
Champ Type Description
status string Le statut de traduction actuel. Les valeurs de statut possibles sont : draft, queued, in_progress, completed, failed, out_of_credit et null.
completeness number Le pourcentage de chaînes traduites (0–100). Calculé comme (completed_translatable_strings / total_translatable_strings) × 100.
Valeurs de statut
Statut Description
draft Le fichier source est enregistré mais n'a pas encore de fichier joint, il n'y a donc rien à traduire.
queued La traduction a été mise en file d'attente et attend d'être traitée.
in_progress La traduction est en cours de traitement.
completed La traduction a été terminée avec succès.
failed La traduction a échoué en raison d'une erreur.
out_of_credit La traduction s'est arrêtée car le projet n'a plus de crédits. Il s'agit d'un état final — l'exécution ne reprend pas d'elle-même une fois les crédits ajoutés, vous devez donc l'interroger périodiquement comme vous le feriez pour failed.
null Aucune traduction n'a encore atteint l'un des statuts ci-dessus. Attendez-vous à cela juste après avoir créé une traduction de contenu, et traitez-le comme « non commencé » plutôt que comme une erreur.

Réponses d'erreur

404 Not Found

Causes possibles :

  • Aucune traduction de contenu n'existe avec l'identifiant spécifié
  • La tâche de traduction n'appartient pas au projet authentifié

Exemple

curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/123/status" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Réponse :

{
  "status": "completed",
  "completeness": 100
}

Réponse pendant que la tâche est encore en cours d'exécution :

{
  "status": "in_progress",
  "completeness": 70
}
{
  "status": "completed",
  "completeness": 100
}