Demander et récupérer les 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 conservant la structure et les clés d’origine. Elle ne traduit que les valeurs de texte, laissant les nombres, les booléens, les valeurs nulles et les autres valeurs non textuelles inchangées.

Créer des traductions de contenu

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

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

Il est particulièrement utile pour :

  • Gestion de contenu – Localisation de contenu dynamique structuré en JSON
  • Fichiers de configuration – Traduction de chaînes destinées à l’utilisateur dans les données de configuration
  • Réponses API – Traduction de charges utiles de réponse structurées
  • Documentation – Localisation de contenu d’aide ou de guides hiérarchiques

Requête HTTP

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

Paramètres

ParamètreTypeObligatoireDescription
dataobjetOuiLes données structurées en JSON à traduire. Elles peuvent inclure des objets imbriqués, des tableaux et des valeurs de chaîne.
namechaîne de caractèresNonUn nom lisible pour la tâche de traduction. S’il est omis, un nom est généré automatiquement.
callback_urlchaîne de caractèresNonL’URL qui reçoit les notifications de webhook lorsque la traduction est terminée.
target_languagestableau[chaîne]NonLe 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 des 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

  • Code : 201 Created
  • Type de contenu : application/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

ChampTypeDescription
idnombreL’identifiant unique de la tâche de traduction de contenu.
namechaîne de caractèresLe nom de la tâche (généré automatiquement s’il n’est pas fourni).
statuschaîne de caractèresL’état actuel de la tâche (queued, processing, completed).
created_atchaîne de caractèresL’horodatage ISO 8601 indiquant la date de création de la tâche.
updated_atchaîne de caractèresL’horodatage ISO 8601 indiquant la date de la dernière mise à jour de la tâche.

Réponses d’erreur

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

Traitement des données JSON

Lorsque vous travaillez avec des 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
  • Prend en charge l’imbrication – Fonctionne avec des objets et des tableaux profondément imbriqués
  • Gère les types de données mixtes – Les valeurs non-chaînes sont conservé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 en un format source interne
  3. Réutilisation de chaînes grâce à 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 des tâches : 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. Rappel (facultatif) : Un webhook est envoyé lorsque toutes les traductions sont terminées, si callback_url est fourni

Rappel de webhook

Lorsqu’un callback_url est fourni, une requête POST est envoyée lorsque la tâche est terminée.

Corps de la requête de rappel :

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

Types de données pris en charge

Type JSONComportement de la traduction
stringTraduit dans les langues cibles
numberConservé tel quel
booleanConservé tel quel
nullConservé tel quel
arrayTraité de manière récursive
objectTraité 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 "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 "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

const translationData = {
  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"
};

const response = await fetch('https://app.ptc.wpml.org/api/v1/content_translation', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(translationData)
});

const result = await response.json();
console.log('Translation job created:', result);

// Store the ID for later retrieval
const translationId = result.id;

import requests

translation_data = {
    "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"
}

headers = {
    'Content-Type': 'application/json'
}

response = requests.post('https://app.ptc.wpml.org/api/v1/content_translation', 
                        headers=headers, json=translation_data)
result = response.json()

print(f"Translation job created with ID: {result['id']}")
print(f"Status: {result['status']}")
<?php
$translationData = [
    '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'
];

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://app.ptc.wpml.org/api/v1/content_translation',
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($translationData),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json'
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

$result = json_decode($response, true);
echo "Translation job created with ID: " . $result['id'];
?>
const axios = require('axios');

const translationData = {
  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"
};

const response = await axios.post('https://app.ptc.wpml.org/api/v1/content_translation', translationData, {
  headers: {
    'Content-Type': 'application/json'
  }
});

console.log('Translation job created:', response.data);

// Monitor status
const checkStatus = async (id) => {
  const statusResponse = await axios.get(`https://app.ptc.wpml.org/api/v1/content_translation/${id}/status`);
  return statusResponse.data.status;
};

Obtenir les traductions de contenu

Récupère le contenu original 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 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ètreTypeObligatoireDescription
identierOuiL’identifiant unique de la tâche de traduction de contenu à récupérer.

Réponses

Réponse de succès

  • Code : 200 OK
  • Type de contenu : application/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

ChampTypeDescription
sourceobjetLe contenu source original dans la même structure imbriquée que celle soumise.
{language_code}objetLe 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 des langues cibles disponibles.

Réponses d’erreur

Traduction de contenu introuvable
  • Code : 404 Not Found
{
  "error": "Content translation not found"
}
Non autorisé
  • Code : 401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Interdit
  • Code : 403 Forbidden
{
  "error": "Access denied. Insufficient permissions."
}

Exemples de requêtes

Requête de base :

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

Exemples de code

const contentTranslationId = 123;

const response = await fetch(`https://app.ptc.wpml.org/api/v1/content_translation/${contentTranslationId}`, {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

// Access source content
console.log('Source title:', data.source.app.title);

// Access translated content
console.log('Spanish title:', data.es.app.title);
console.log('French title:', data.fr.app.title);

// Iterate through all languages
Object.keys(data).forEach(langCode => {
  if (langCode !== 'source') {
    console.log(`${langCode} translation:`, data[langCode]);
  }
});
import requests

content_translation_id = 123
headers = {
    'Content-Type': 'application/json'
}

response = requests.get(f'https://app.ptc.wpml.org/api/v1/content_translation/{content_translation_id}', 
                       headers=headers)
data = response.json()

# Access source content
source_data = data['source']
print("Source content:", source_data)

# Access translations
for lang_code, translation in data.items():
    if lang_code != 'source':
        print(f"{lang_code.upper()} translation:", translation)
<?php
$content_translation_id = 123;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://app.ptc.wpml.org/api/v1/content_translation/{$content_translation_id}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json'
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

$data = json_decode($response, true);

// Access source content
$sourceData = $data['source'];
echo "Source content: " . json_encode($sourceData, JSON_PRETTY_PRINT) . "\n";

// Access translations
foreach ($data as $langCode => $translation) {
    if ($langCode !== 'source') {
        echo strtoupper($langCode) . " translation: " . json_encode($translation, JSON_PRETTY_PRINT) . "\n";
    }
}
?>
const axios = require('axios');

const contentTranslationId = 123;

const response = await axios.get(`https://app.ptc.wpml.org/api/v1/content_translation/${contentTranslationId}`, {
  headers: {
    'Content-Type': 'application/json'
  }
});

const data = response.data;

// Function to traverse nested objects
function extractStrings(obj, path = '') {
  const strings = [];
  for (const [key, value] of Object.entries(obj)) {
    const currentPath = path ? `${path}.${key}` : key;
    if (typeof value === 'string') {
      strings.push({ path: currentPath, value });
    } else if (typeof value === 'object') {
      strings.push(...extractStrings(value, currentPath));
    }
  }
  return strings;
}

// Extract all translatable strings
const sourceStrings = extractStrings(data.source);
console.log('Source strings:', sourceStrings);

// Compare with translations
Object.keys(data).forEach(langCode => {
  if (langCode !== 'source') {
    const translatedStrings = extractStrings(data[langCode]);
    console.log(`${langCode} strings:`, translatedStrings);
  }
});

Obtenir le statut de la traduction du 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ètreTypeObligatoireDescription
identierOuiL’identifiant unique de la tâche de traduction de contenu à vérifier.

Réponses

Réponse de succès

  • Code : 200 OK
  • Type de contenu : application/json
{
  "status": "completed",
  "completeness": 100
}
Schéma de réponse
ChampTypeDescription
statuschaîne de caractèresLe statut de traduction actuel. Les valeurs de statut possibles incluent : queued, in_progress, completed, failed, status_unknown.
completenessnombreLe pourcentage de chaînes traduites (0–100). Calculé comme (completed_translatable_strings / total_translatable_strings) × 100.
Valeurs de statut
StatutDescription
queuedLa traduction a été mise en file d’attente et est en attente de traitement.
in_progressLa traduction est en cours de traitement.
completedLa traduction a été effectuée avec succès.
failedLa traduction a échoué en raison d’une erreur.
status_unknownLe statut de la traduction est inconnu ou ne peut pas encore être déterminé.

Réponses d’erreur

  • Code : 404 Not Found

Causes possibles :

  • Aucune traduction de contenu n’existe avec l’ID 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
}
GET https://app.ptc.wpml.org/api/v1/content_translation/{id}/status
{
  "status": "in_progress",
  "completeness": 70
}
curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/123/status" \
  -H "Authorization: Bearer your-api-token"
{
  "status": "completed",
  "completeness": 100
}

Faire défiler vers le haut