Richiedi e recupera le traduzioni tramite l’API

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.

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

ParametroTipoObbligatorioDescrizione
dataobjectI dati strutturati in formato JSON da tradurre. Possono includere oggetti nidificati, array e valori stringa.
namestringaNoUn nome leggibile per il lavoro di traduzione. Se omesso, ne viene generato uno automaticamente.
callback_urlstringaNoL’URL che riceve le notifiche webhook quando la traduzione è completa.
target_languagesarray[string]NoL’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

CampoTipoDescrizione
idnumeroL’identificatore univoco del lavoro di traduzione dei contenuti.
namestringaIl nome del lavoro (generato automaticamente se non fornito).
statusstringaLo stato attuale del lavoro (queued, processing, completed).
created_atstringaIl timestamp ISO 8601 che indica quando è stato creato il lavoro.
updated_atstringaIl 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 tradotto
  • user.settings.theme: “Choose Theme” → Viene tradotto
  • user.settings.count: 5 → Rimane invariato
  • user.settings.enabled: true → Rimane invariato

Flusso di lavoro della traduzione

  1. Validazione: vengono controllati la struttura JSON e le lingue di destinazione
  2. Preparazione del file sorgente: il JSON viene convertito in un formato sorgente interno
  3. 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
  4. Accodamento del lavoro: un lavoro viene accodato per ogni lingua di destinazione
  5. Elaborazione: la traduzione automatica viene eseguita sulle stringhe estratte
  6. 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 JSONComportamento della traduzione
stringTradotto nelle lingue di destinazione
numberPreservato così com’è
booleanPreservato così com’è
nullPreservato così com’è
arrayElaborato ricorsivamente
objectElaborato 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

ParametroTipoObbligatorioDescrizione
idinteroL’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

CampoTipoDescrizione
sourceobjectIl contenuto sorgente originale nella stessa struttura nidificata di quella inviata.
{language_code}objectIl 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

ParametroTipoObbligatorioDescrizione
idinteroL’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
CampoTipoDescrizione
statusstringaLo stato attuale della traduzione. I possibili valori di stato includono: queued, in_progress, completed, failed, status_unknown.
completenessnumeroLa percentuale di stringhe tradotte (0–100). Calcolata come (completed_translatable_strings / total_translatable_strings) × 100.
Valori di stato
StatoDescrizione
queuedLa traduzione è stata messa in coda ed è in attesa di essere elaborata.
in_progressLa traduzione è attualmente in fase di elaborazione.
completedLa traduzione è stata completata con successo.
failedLa traduzione non è riuscita a causa di un errore.
status_unknownLo 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
}

Scorri verso l'alto