Utilizza questa API per inviare contenuti da tradurre, monitorarne l’avanzamento e recuperare le traduzioni in tutte le lingue di destinazione.
Questa API accetta contenuti strutturati in formato JSON, preservando la struttura e le chiavi originali. Traduce solo i valori di testo, lasciando invariati numeri, booleani, valori null e altri valori non testuali.
Link rapidi API
Crea traduzioni di contenuti
Crea un nuovo lavoro di traduzione da dati strutturati in formato JSON.
L’endpoint preserva la gerarchia originale di chiavi e array del tuo contenuto, traducendo solo i valori di testo e lasciando invariati numeri, booleani, valori null e altri valori non testuali.
È particolarmente utile per:
- Gestione dei contenuti – Localizzazione di contenuti dinamici strutturati in JSON
- File di configurazione – Traduzione di stringhe rivolte all’utente nei dati di configurazione
- Risposte API – Traduzione di payload di risposta strutturati
- Documentazione – Localizzazione di contenuti o guide di aiuto gerarchici
Richiesta HTTP
POST https://app.ptc.wpml.org/api/v1/content_translation
Parametri
Parametro | Tipo | Obbligatorio | Descrizione |
---|---|---|---|
data | object | Sì | I dati strutturati in formato JSON da tradurre. Possono includere oggetti nidificati, array e valori stringa. |
name | stringa | No | Un nome leggibile per il lavoro di traduzione. Se omesso, ne viene generato uno automaticamente. |
callback_url | stringa | No | L’URL che riceve le notifiche webhook quando la traduzione è completa. |
target_languages | array[string] | No | L’array di codici ISO per le lingue di destinazione. Se omesso, le traduzioni vengono create per tutte le lingue configurate nel progetto. Consulta l’API Lingue di destinazione disponibili per maggiori informazioni. |
Esempio di corpo della richiesta
{
"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"]
}
Risposte
Risposta di successo
- Codice:
201 Created
- Tipo di contenuto:
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"
}
Schema di risposta
Campo | Tipo | Descrizione |
---|---|---|
id | numero | L’identificatore univoco del lavoro di traduzione dei contenuti. |
name | stringa | Il nome del lavoro (generato automaticamente se non fornito). |
status | stringa | Lo stato attuale del lavoro (queued , processing , completed ). |
created_at | stringa | Il timestamp ISO 8601 che indica quando è stato creato il lavoro. |
updated_at | stringa | Il timestamp ISO 8601 che indica quando è stato aggiornato l’ultima volta il lavoro. |
Risposte di errore
Dati JSON non validi
- Codice:
422 Unprocessable Entity
{
"errors": {
"data": ["Data must be a valid JSON object"]
}
}
Lingue di destinazione non valide
- Codice:
422 Unprocessable Entity
{
"errors": {
"target_languages": ["Language codes [zh, xx] are not configured for this project"]
}
}
Non autorizzato
- Codice:
401 Unauthorized
{
"error": "Unauthorized access. Please provide a valid API token."
}
Proibito
- Codice:
403 Forbidden
{
"error": "Access denied. Insufficient permissions."
}
Elaborazione dei dati JSON
Quando si lavora con dati strutturati in formato JSON, PTC elabora i dati come segue:
- La struttura viene preservata – La gerarchia originale di chiavi e nidificazione rimane invariata
- Vengono tradotte solo le stringhe – Numeri, booleani, array e valori null vengono mantenuti così come sono
- Traduzione basata sul percorso – Ogni stringa traducibile è identificata dal suo percorso JSON
- Supporta la nidificazione – Funziona con oggetti e array profondamente nidificati
- Gestisce tipi di dati misti – I valori non stringa vengono preservati senza modifiche
Esempio di trasformazione dei dati
Input:
{
"user": {
"name": "Welcome User",
"settings": {
"theme": "Choose Theme",
"count": 5,
"enabled": true
}
}
}
Esito dell’elaborazione:
user.name
: “Welcome User” → Viene tradottouser.settings.theme
: “Choose Theme” → Viene tradottouser.settings.count:
5 → Rimane invariatouser.settings.enabled:
true → Rimane invariato
Flusso di lavoro della traduzione
- Validazione: vengono controllati la struttura JSON e le lingue di destinazione
- Preparazione del file sorgente: il JSON viene convertito in un formato sorgente interno
- Riutilizzo delle stringhe tramite la translation memory: tutte le stringhe traducibili vengono estratte e memorizzate nella translation memory del tuo progetto in modo che le traduzioni precedenti possano essere riutilizzate
- Accodamento del lavoro: un lavoro viene accodato per ogni lingua di destinazione
- Elaborazione: la traduzione automatica viene eseguita sulle stringhe estratte
- Callback (opzionale): viene inviato un webhook quando tutte le traduzioni sono completate, se
callback_url
è fornito
Webhook callback
Quando viene fornito un callback_url
, viene inviata una richiesta POST
quando il lavoro è completato.
Corpo della richiesta di callback:
{
"id": 1,
"status": "completed",
"translations_url": "https://app.ptc.wpml.org/api/v1/content_translation/1"
}
Tipi di dati supportati
Tipo JSON | Comportamento della traduzione |
---|---|
string | Tradotto nelle lingue di destinazione |
number | Preservato così com’è |
boolean | Preservato così com’è |
null | Preservato così com’è |
array | Elaborato ricorsivamente |
object | Elaborato ricorsivamente |
Esempi di richieste
Traduzione JSON di 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"
}'
Con lingue di destinazione specifiche:
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"
}'
Esempi di codice
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;
};
Ottieni traduzioni di contenuti
Recupera il contenuto originale e tutte le versioni tradotte per uno specifico lavoro di traduzione dei contenuti.
La risposta preserva la struttura di input: restituisce un oggetto sorgente più un oggetto per ogni lingua di destinazione (identificati dal codice lingua come es
, fr
, de
).
Richiesta HTTP
GET https://app.ptc.wpml.org/api/v1/content_translation/{id}
Parametri del percorso
Parametro | Tipo | Obbligatorio | Descrizione |
---|---|---|---|
id | intero | Sì | L’identificatore univoco del lavoro di traduzione dei contenuti da recuperare. |
Risposte
Risposta di successo
- Codice:
200 OK
- Tipo di contenuto:
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"
}
}
}
}
Schema di risposta
Campo | Tipo | Descrizione |
---|---|---|
source | object | Il contenuto sorgente originale nella stessa struttura nidificata di quella inviata. |
{language_code} | object | Il contenuto tradotto per ogni lingua di destinazione, identificato dal suo codice ISO (ad esempio es , fr , de ), con la stessa struttura della sorgente.Per maggiori informazioni, consulta l’API Lingue di destinazione disponibili. |
Risposte di errore
Traduzione dei contenuti non trovata
- Codice:
404 Not Found
{
"error": "Content translation not found"
}
Non autorizzato
- Codice:
401 Unauthorized
{
"error": "Unauthorized access. Please provide a valid API token."
}
Proibito
- Codice:
403 Forbidden
{
"error": "Access denied. Insufficient permissions."
}
Esempi di richieste
Richiesta di base:
curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/123" \
-H "Content-Type: application/json"
Esempi di codice
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);
}
});
Ottieni lo stato della traduzione dei contenuti
Recupera lo stato attuale di un job di traduzione di contenuti specifico.
La risposta riflette l’avanzamento complessivo e include se la traduzione è in coda, in corso, completata o non è riuscita.
Richiesta HTTP
GET https://app.ptc.wpml.org/api/v1/content_translation/{id}/status
Parametri del percorso
Parametro | Tipo | Obbligatorio | Descrizione |
---|---|---|---|
id | intero | Sì | L’identificatore univoco del job di traduzione di contenuti da controllare. |
Risposte
Risposta di successo
- Codice:
200 OK
- Tipo di contenuto:
application/json
{
"status": "completed",
"completeness": 100
}
Schema di risposta
Campo | Tipo | Descrizione |
---|---|---|
status | stringa | Lo stato attuale della traduzione. I possibili valori di stato includono: queued , in_progress , completed , failed , status_unknown . |
completeness | numero | La percentuale di stringhe tradotte (0–100). Calcolata come (completed_translatable_strings / total_translatable_strings) × 100 . |
Valori di stato
Stato | Descrizione |
---|---|
queued | La traduzione è stata messa in coda ed è in attesa di essere elaborata. |
in_progress | La traduzione è attualmente in fase di elaborazione. |
completed | La traduzione è stata completata con successo. |
failed | La traduzione non è riuscita a causa di un errore. |
status_unknown | Lo stato della traduzione è sconosciuto o non può ancora essere determinato. |
Risposte di errore
- Codice:
404 Not Found
Cause possibili:
- Non esiste alcuna traduzione di contenuti con l’ID specificato
- Il job di traduzione non appartiene al progetto autenticato
Esempio
curl -X GET "https://app.ptc.wpml.org/api/v1/content_translation/123/status" \
-H "Authorization: Bearer your-api-token"
Risposta:
{
"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
}