Richiedi e recupera le traduzioni tramite l'API
Usa questa API per inviare contenuti per la traduzione, 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 di testo, lasciando inalterati numeri, booleani, valori null e altri valori non di testo.
Link rapidi dell'API
Create Content Translations
Crea un nuovo job di traduzione a partire da dati strutturati in JSON.
L'endpoint preserva la gerarchia originale di chiavi e array dei tuoi contenuti, traducendo solo i valori di testo e lasciando inalterati numeri, booleani, valori null e altri valori non testuali.
È particolarmente utile per:
- Gestione dei contenuti – Localizzare il contenuto dinamico strutturato in JSON
- File di configurazione – Tradurre le stringhe destinate agli utenti nei dati di configurazione
- Risposte dell'API – Tradurre i payload strutturati delle risposte
- Documentazione – Localizzare contenuti di guida o manuali gerarchici
Per un'implementazione completa in Rails di questo flusso di lavoro, vedi tradurre il contenuto dinamico in Rails usando l'API di PTC.
Richiesta HTTP
POST https://app.ptc.wpml.org/api/v1/content_translationParametri
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
data |
oggetto | Sì | I dati strutturati in JSON da tradurre. Possono includere oggetti annidati, array e valori stringa. |
name |
stringa | No | Un nome leggibile per il job di traduzione. Se omesso, ne viene generato uno automaticamente. |
callback_url |
stringa | No | L'URL che riceve le notifiche webhook al completamento della traduzione. |
target_languages |
array[stringa] | No | L'array di codici ISO per le lingue di destinazione. Se omesso, le traduzioni vengono create per tutte le lingue configurate nel progetto. Per maggiori informazioni, consulta le API Lingue di destinazione disponibili. |
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 |
numero | L'identificatore univoco del job di traduzione dei contenuti. |
name |
stringa | Il nome del job (generato automaticamente se non fornito). |
status |
stringa | Lo stato attuale del job (queued, processing, completed). |
created_at |
stringa | Il timestamp ISO 8601 che indica quando è stato creato il job. |
updated_at |
stringa | Il timestamp ISO 8601 che indica quando il job è 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."
}Accesso negato
{
"error": "Access denied. Insufficient permissions."
}Elaborazione dei dati JSON
Quando lavori con dati strutturati in JSON, PTC elabora i dati nel modo seguente:
- La struttura viene preservata – La gerarchia originale delle chiavi e l'annidamento rimangono invariati
- 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 l'annidamento – Funziona con oggetti e array profondamente annidati
- 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 → Rimane inalteratouser.settings.enabled:true → Rimane inalterato
Flusso di lavoro di traduzione
- Convalida: vengono verificati la struttura JSON e le lingue di destinazione
- Preparazione del file di origine: il JSON viene convertito in un formato di origine interno
- Riutilizzo delle stringhe tramite la memoria di traduzione: tutte le stringhe traducibili vengono estratte e archiviate nella memoria di traduzione del tuo progetto, in modo da poter riutilizzare le traduzioni precedenti
- Accodamento dei job: viene messo in coda un job 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 viene fornito
callback_url
Callback webhook
Quando viene fornito un callback_url, al completamento del job viene inviata una richiesta POST.
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 di 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)`);Get Content Translations
Recupera il contenuto originale e tutte le versioni tradotte per uno specifico job di traduzione dei contenuti.
La risposta preserva la struttura di input: restituisce un oggetto di origine più un oggetto per ciascuna lingua di destinazione (indicizzato dal codice della lingua, come es, fr, de).
Richiesta HTTP
GET https://app.ptc.wpml.org/api/v1/content_translation/{id}Parametri di percorso
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
id |
intero | Sì | L'identificatore univoco del job di traduzione dei contenuti 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 |
oggetto | Il contenuto di origine originale, nella stessa struttura annidata in cui è stato inviato. |
{language_code} |
oggetto | Il contenuto tradotto per ogni lingua di destinazione, indicizzato in base al suo codice ISO (ad esempio es, fr, de), con la stessa struttura dell'origine. Per maggiori informazioni, consulta le API Lingue di destinazione disponibili. |
Risposte di errore
Traduzione dei contenuti non trovata
{
"error": "Content translation not found"
}Non autorizzato
{
"error": "Unauthorized access. Please provide a valid API token."
}Accesso negato
{
"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]);
});Get the Content Translation Status
Recupera lo stato attuale di uno specifico job di traduzione dei contenuti.
La risposta riflette l'avanzamento complessivo e indica se la traduzione è in coda, in corso, completata o non riuscita.
Richiesta HTTP
GET https://app.ptc.wpml.org/api/v1/content_translation/{id}/statusParametri di percorso
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
id |
intero | Sì | L'identificatore univoco del job di traduzione dei contenuti da controllare. |
Risposte
Risposta di successo
{
"status": "completed",
"completeness": 100
}Schema della risposta
| Campo | Tipo | Descrizione |
|---|---|---|
status |
stringa | L'attuale stato 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
Cause possibili:
- Non esiste alcuna traduzione dei 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
}Risposta mentre il job è ancora in esecuzione:
{
"status": "in_progress",
"completeness": 70
}{
"status": "completed",
"completeness": 100
}