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 du contenu structuré en JSON, en préservant la structure et les clés d'origine. Elle traduit uniquement les valeurs textuelles, en laissant les nombres, les booléens, les valeurs nulles et les autres valeurs non textuelles inchangés.
Liens rapides de l'API
Create Content Translations
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 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 les 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 complète de ce flux de travail dans Rails, consultez la section traduire du contenu dynamique dans Rails à l'aide de l'API PTC.
Requête HTTP
POST https://app.ptc.wpml.org/api/v1/content_translationParamè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 type chaîne. |
name |
string | Non | Un nom lisible par l'homme 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 des 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
{
"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 le moment où la tâche a été créée. |
updated_at |
string | L'horodatage ISO 8601 indiquant le moment où la tâche a été mise à jour pour la dernière fois. |
Réponses d'erreur
Données JSON invalides
{
"errors": {
"data": ["Data must be a valid JSON object"]
}
}Langues cibles invalides
{
"errors": {
"target_languages": ["Language codes [zh, xx] are not configured for this project"]
}
}Non autorisé
{
"error": "Unauthorized access. Please provide a valid API token."
}Interdit
{
"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 l'imbrication restent inchangées
- 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 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 traduiteuser.settings.theme: « Choose Theme » → Est traduiteuser.settings.count:5 → Reste inchangéuser.settings.enabled:true → Reste inchangé
Flux de travail de traduction
- Validation : La structure JSON et les langues cibles sont vérifiées
- Préparation du fichier source : Le JSON est converti vers un format source interne
- 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
- Mise en file d'attente : Une tâche est mise en file d'attente pour chaque langue cible
- Traitement : La traduction automatique s'exécute sur les chaînes extraites
- Callback (facultatif) : Un webhook est envoyé lorsque toutes les traductions sont terminées, si
callback_urlest fourni
Callback 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 vers les langues cibles |
number |
Préservé tel quel |
boolean |
Préservé tel quel |
null |
Préservé 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"require 'net/http'
require 'uri'
require 'json'
uri = URI('https://app.ptc.wpml.org/api/v1/content_translation')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
data: { app: { title: 'My Application',
navigation: { home: 'Home', about: 'About Us' } } },
name: 'App Translations',
target_languages: %w[es fr de],
callback_url: 'https://your-app.com/webhooks/complete'
}.to_json
response = http.request(request)
id = JSON.parse(response.body)['id']
puts "Translation job created with ID: #{id}"
# Poll the status endpoint for progress (status is set there, not on create)
status_uri = URI("https://app.ptc.wpml.org/api/v1/content_translation/#{id}/status")
status_request = Net::HTTP::Get.new(status_uri)
status_request['Authorization'] = 'Bearer YOUR_API_TOKEN'
status = JSON.parse(http.request(status_request).body)
puts "Status: #{status['status']} (#{status['completeness']}% complete)"import requests
headers = {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json'
}
payload = {
"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"
}
response = requests.post('https://app.ptc.wpml.org/api/v1/content_translation', headers=headers, json=payload)
translation_id = response.json()['id']
print(f"Translation job created with ID: {translation_id}")
# Poll the status endpoint for progress (status is set there, not on create)
status_response = requests.get(f'https://app.ptc.wpml.org/api/v1/content_translation/{translation_id}/status', headers=headers)
status = status_response.json()
print(f"Status: {status['status']} ({status['completeness']}% complete)")<?php
$payload = [
'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($payload),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_API_TOKEN',
'Content-Type: application/json'
],
]);
$response = curl_exec($curl);
curl_close($curl);
$id = json_decode($response, true)['id'];
echo "Translation job created with ID: " . $id . "\n";
// Poll the status endpoint for progress (status is set there, not on create)
$statusCurl = curl_init();
curl_setopt_array($statusCurl, [
CURLOPT_URL => "https://app.ptc.wpml.org/api/v1/content_translation/{$id}/status",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_TOKEN'],
]);
$status = json_decode(curl_exec($statusCurl), true);
curl_close($statusCurl);
echo "Status: " . $status['status'] . " (" . $status['completeness'] . "% complete)";
?>import okhttp3.*;
OkHttpClient client = new OkHttpClient();
MediaType JSON = MediaType.parse("application/json");
String payload = "{"
+ "\"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\"}";
Request request = new Request.Builder()
.url("https://app.ptc.wpml.org/api/v1/content_translation")
.addHeader("Authorization", "Bearer YOUR_API_TOKEN")
.post(RequestBody.create(payload, JSON))
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());package main
import (
"bytes"
"fmt"
"io"
"net/http"
)
func main() {
payload := []byte(`{
"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"
}`)
req, _ := http.NewRequest("POST", "https://app.ptc.wpml.org/api/v1/content_translation", bytes.NewBuffer(payload))
req.Header.Add("Authorization", "Bearer YOUR_API_TOKEN")
req.Header.Add("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Text;
var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "YOUR_API_TOKEN");
var payload = @"{
""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""
}";
var body = new StringContent(payload, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://app.ptc.wpml.org/api/v1/content_translation", body);
var content = await response.Content.ReadAsStringAsync();
Console.WriteLine(content);const axios = require('axios');
const payload = {
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', payload, {
headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
});
const translationId = response.data.id;
console.log('Translation job created with ID:', translationId);
// Poll the status endpoint for progress (status is set there, not on create)
const status = await axios.get(`https://app.ptc.wpml.org/api/v1/content_translation/${translationId}/status`, {
headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
});
console.log(`Status: ${status.data.status} (${status.data.completeness}% complete)`);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 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
{
"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
{
"error": "Content translation not found"
}Non autorisé
{
"error": "Unauthorized access. Please provide a valid API token."
}Interdit
{
"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"require 'net/http'
require 'uri'
uri = URI('https://app.ptc.wpml.org/api/v1/content_translation/123')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
response = http.request(request)
require 'json'
data = JSON.parse(response.body)
puts "Source: #{data['source']}"
data.each { |lang, translation| puts "#{lang}: #{translation}" unless lang == 'source' }import requests
headers = {
'Authorization': 'Bearer YOUR_API_TOKEN'
}
response = requests.get('https://app.ptc.wpml.org/api/v1/content_translation/123', headers=headers)
data = response.json()
print('Source:', data['source'])
for lang_code, translation in data.items():
if lang_code != 'source':
print(f"{lang_code}:", translation)<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'https://app.ptc.wpml.org/api/v1/content_translation/123',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_API_TOKEN'
],
]);
$response = curl_exec($curl);
curl_close($curl);
$data = json_decode($response, true);
foreach ($data as $langCode => $translation) {
echo strtoupper($langCode) . ": " . json_encode($translation) . "\n";
}
?>import okhttp3.*;
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://app.ptc.wpml.org/api/v1/content_translation/123")
.addHeader("Authorization", "Bearer YOUR_API_TOKEN")
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://app.ptc.wpml.org/api/v1/content_translation/123", nil)
req.Header.Add("Authorization", "Bearer YOUR_API_TOKEN")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
using System;
using System.Net.Http;
using System.Threading.Tasks;
var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "YOUR_API_TOKEN");
var response = await client.GetAsync("https://app.ptc.wpml.org/api/v1/content_translation/123");
var content = await response.Content.ReadAsStringAsync();
Console.WriteLine(content);const axios = require('axios');
const response = await axios.get('https://app.ptc.wpml.org/api/v1/content_translation/123', {
headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
});
const data = response.data;
console.log('Source:', data.source);
Object.keys(data).forEach(lang => {
if (lang !== 'source') console.log(`${lang}:`, data[lang]);
});Get the Content Translation Status
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}/statusParamè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
{
"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é selon la formule (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 actuellement 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 mots. Il s'agit d'un état final — l'exécution ne reprend pas d'elle-même une fois que des mots supplémentaires sont ajoutés, interrogez-la donc périodiquement comme vous le feriez pour failed. |
null |
Aucune traduction n'a encore atteint l'un des statuts ci-dessus. Attendez-vous à ce résultat juste après avoir créé une traduction de contenu, et traitez-le comme « non démarré » plutôt que comme une erreur. |
Réponses d'erreur
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
}Réponse pendant que la tâche est encore en cours d'exécution :
{
"status": "in_progress",
"completeness": 70
}{
"status": "completed",
"completeness": 100
}