Richiedi e recupera traduzioni tramite l’API
Usa 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 JSON, preservando la struttura e le chiavi originali. Traduce solo i valori testuali, lasciando invariati numeri, booleani, null e altri valori non testuali.
Link rapidi API
- Crea traduzioni di contenuti
- Ottieni traduzioni di contenuti
- Ottieni lo stato della traduzione del contenuto
Crea traduzioni di contenuti
Crea un nuovo lavoro di traduzione da dati strutturati in JSON.
L’endpoint preserva la gerarchia originale di chiavi e array del tuo contenuto, traducendo solo i valori testuali e lasciando invariati numeri, booleani, 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 di aiuto o guide gerarchiche
Per un’implementazione completa di questo workflow in Rails, consulta come tradurre contenuti dinamici in Rails utilizzando l’API di PTC.
Richiesta HTTP
POST https://app.ptc.wpml.org/api/v1/content_translationParametri
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
data |
object | Sì | I dati strutturati in JSON da tradurre. Può includere oggetti nidificati, array e valori stringa. |
name |
string | No | Un nome leggibile per il lavoro di traduzione. Se omesso, ne viene generato uno automaticamente. |
callback_url |
string | No | L’URL che riceve le notifiche webhook quando la traduzione è completata. |
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 per le 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
{
"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 della risposta
| Campo | Tipo | Descrizione |
|---|---|---|
id |
number | L’identificatore univoco del lavoro di traduzione del contenuto. |
name |
string | Il nome del lavoro (generato automaticamente se non fornito). |
status |
string | Lo stato attuale del lavoro (queued, processing, completed). |
created_at |
string | Il timestamp ISO 8601 che indica quando il lavoro è stato creato. |
updated_at |
string | Il timestamp ISO 8601 che indica quando il lavoro è stato aggiornato l’ultima volta. |
Risposte di errore
Dati JSON non validi
{
"errors": {
"data": ["Data must be a valid JSON object"]
}
}Lingue di destinazione non valide
{
"errors": {
"target_languages": ["Language codes [zh, xx] are not configured for this project"]
}
}Non autorizzato
{
"error": "Unauthorized access. Please provide a valid API token."
}Vietato
{
"error": "Access denied. Insufficient permissions."
}Elaborazione dei dati JSON
Quando lavori con dati strutturati in JSON, PTC elabora i dati come segue:
- La struttura viene preservata – La gerarchia originale delle chiavi e delle nidificazioni 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
}
}
}Risultato dell’elaborazione:
user.name: “Welcome User” → Viene tradottouser.settings.theme: “Choose Theme” → Viene tradottouser.settings.count:5 → Resta invariatouser.settings.enabled:true → Resta invariato
Workflow di traduzione
- Validazione: vengono controllati la struttura JSON e le lingue di destinazione
- Preparazione del file di origine: il JSON viene convertito in un formato di origine interno
- Riuso delle stringhe tramite memoria di traduzione: tutte le stringhe traducibili vengono estratte e memorizzate nella memoria di traduzione del tuo progetto, in modo che le traduzioni precedenti possano essere riutilizzate
- Accodamento del lavoro: viene messo in coda un lavoro per ogni lingua di destinazione
- Elaborazione: la traduzione automatica viene eseguita sulle stringhe estratte
- Callback (opzionale): se viene fornito un
callback_url, viene inviato un webhook al completamento di tutte le traduzioni
Callback Webhook
Quando viene fornito un callback_url, viene inviata una richiesta POST al completamento del lavoro.
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 "Authorization: Bearer YOUR_API_TOKEN" \
-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 "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"
}'Esempi di codice
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 (status stays
# "in_progress" until done — it is not set on the create response):
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)`);Ottieni traduzioni di contenuti
Recupera il contenuto originale e tutte le versioni tradotte per uno specifico lavoro di traduzione del contenuto.
La risposta preserva la struttura del tuo input: restituisce un oggetto sorgente più un oggetto per ogni lingua di destinazione (identificato 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 |
integer | Sì | L’identificatore univoco del lavoro di traduzione del contenuto da recuperare. |
Risposte
Risposta di successo
{
"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 della risposta
| Campo | Tipo | Descrizione |
|---|---|---|
source |
object | Il contenuto originale di origine nella stessa struttura nidificata 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 dell’origine. Per maggiori informazioni, consulta l’API per le lingue di destinazione disponibili. |
Risposte di errore
Traduzione del contenuto non trovata
{
"error": "Content translation not found"
}Non autorizzato
{
"error": "Unauthorized access. Please provide a valid API token."
}Vietato
{
"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 "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json"Esempi di codice
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]);
});Ottieni lo stato della traduzione del contenuto
Recupera lo stato attuale di uno specifico lavoro di traduzione del contenuto.
La risposta riflette l’avanzamento complessivo e indica se la traduzione è in coda, in corso, completata o se è fallita.
Richiesta HTTP
GET https://app.ptc.wpml.org/api/v1/content_translation/{id}/statusParametri del percorso
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
id |
integer | Sì | L’identificatore univoco del lavoro di traduzione del contenuto da controllare. |
Risposte
Risposta di successo
{
"status": "completed",
"completeness": 100
}Schema della risposta
| Campo | Tipo | Descrizione |
|---|---|---|
status |
string | Lo stato attuale della traduzione. I possibili valori di stato includono: queued, in_progress, completed, failed, status_unknown. |
completeness |
number | 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 è fallita a causa di un errore. |
status_unknown |
Lo stato della traduzione è sconosciuto o non può ancora essere determinato. |
Risposte di errore
Possibili cause:
- Non esiste alcuna traduzione del contenuto con l’ID specificato
- Il lavoro 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
}Risposta mentre il lavoro è ancora in esecuzione:
{
"status": "in_progress",
"completeness": 70
}{
"status": "completed",
"completeness": 100
}