PTC

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.

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_translation

Parametri

Parametro Tipo Obbligatorio Descrizione
data object 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

201 Createdapplication/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 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
422 Unprocessable Entity
{
  "errors": {
    "data": ["Data must be a valid JSON object"]
  }
}
Lingue di destinazione non valide
422 Unprocessable Entity
{
  "errors": {
    "target_languages": ["Language codes [zh, xx] are not configured for this project"]
  }
}
Non autorizzato
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Vietato
403 Forbidden
{
  "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 tradotto
  • user.settings.theme: “Choose Theme” → Viene tradotto
  • user.settings.count: 5 → Resta invariato
  • user.settings.enabled: true → Resta invariato

Workflow di traduzione

  1. Validazione: vengono controllati la struttura JSON e le lingue di destinazione
  2. Preparazione del file di origine: il JSON viene convertito in un formato di origine interno
  3. 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
  4. Accodamento del lavoro: viene messo in coda un lavoro per ogni lingua di destinazione
  5. Elaborazione: la traduzione automatica viene eseguita sulle stringhe estratte
  6. 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"

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 L’identificatore univoco del lavoro di traduzione del contenuto da recuperare.

Risposte

Risposta di successo

200 OKapplication/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 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
404 Not Found
{
  "error": "Content translation not found"
}
Non autorizzato
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Vietato
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 "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"

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}/status

Parametri del percorso

Parametro Tipo Obbligatorio Descrizione
id integer L’identificatore univoco del lavoro di traduzione del contenuto da controllare.

Risposte

Risposta di successo

200 OKapplication/json
{
  "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

404 Not Found

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
}