PTC

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.

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_translation

Parametri

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

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 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
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."
}
Accesso negato
403 Forbidden
{
  "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 tradotto
  • user.settings.theme: “Choose Theme” → Viene tradotto
  • user.settings.count: 5 → Rimane inalterato
  • user.settings.enabled: true → Rimane inalterato

Flusso di lavoro di traduzione

  1. Convalida: vengono verificati 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. 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
  4. Accodamento dei job: viene messo in coda un job 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 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"

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 L'identificatore univoco del job di traduzione dei contenuti 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 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
404 Not Found
{
  "error": "Content translation not found"
}
Non autorizzato
401 Unauthorized
{
  "error": "Unauthorized access. Please provide a valid API token."
}
Accesso negato
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"

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

Parametri di percorso

Parametro Tipo Obbligatorio Descrizione
id intero L'identificatore univoco del job di traduzione dei contenuti da controllare.

Risposte

Risposta di successo

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

404 Not Found

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
}