PTC

Richiedi e recupera le 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 di testo, lasciando inalterati i numeri, i valori booleani, i valori null e altri valori non testuali.

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 i numeri, i valori booleani, i 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 rivolte all'utente nei dati di configurazione
  • Risposte API – Tradurre i payload di risposta strutturati
  • Documentazione – Localizzare contenuti di guida o manuali gerarchici

Per un'implementazione completa di questo flusso di lavoro in Rails, vedi la traduzione del 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 object Sì I dati strutturati in JSON da tradurre. Possono includere oggetti nidificati, array e valori stringa.
name string No Un nome leggibile per il job di traduzione. Se omesso, ne viene generato uno automaticamente.
callback_url string No L'URL che riceve le notifiche webhook al completamento della traduzione.
target_languages array[string] No L'array dei codici ISO per le lingue di destinazione. Se omesso, vengono create le traduzioni per tutte le lingue configurate nel progetto. Per maggiori informazioni, consulta l'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 number L'identificatore univoco del job di traduzione dei contenuti.
name string Il nome del job (generato automaticamente se non fornito).
status string Lo stato attuale del job (queued, processing, completed).
created_at string Il timestamp ISO 8601 che indica quando è stato creato il job.
updated_at string Il timestamp ISO 8601 che indica quando il job è stato aggiornato per 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 si lavora con dati strutturati in JSON, PTC elabora i dati nel modo seguente:

  • La struttura viene preservata – La gerarchia originale delle chiavi e la nidificazione rimangono inalterate
  • Vengono tradotte solo le stringhe – I numeri, i valori booleani, gli array e i valori null vengono mantenuti così come sono
  • Traduzione basata sul percorso – Ogni stringa traducibile viene 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 → Rimane inalterato
  • user.settings.enabled: true → Rimane inalterato

Flusso di lavoro della 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, viene inviata una richiesta POST al completamento del job.

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 in modo ricorsivo
object Elaborato in modo ricorsivo

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 (the create response
# carries a "status" field as well, but it is usually null until the run
# starts, and stays "in_progress" until done):
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 ogni lingua di destinazione (con codice lingua come chiave, ad esempio es, fr, de).

Richiesta HTTP

GET https://app.ptc.wpml.org/api/v1/content_translation/{id}

Parametri di percorso

Parametro Tipo Obbligatorio Descrizione
id integer Sì 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 object Il contenuto di origine originale nella stessa struttura nidificata inviata.
{language_code} object Il contenuto tradotto per ogni lingua di destinazione, con il relativo codice ISO come chiave (ad esempio es, fr, de), con la stessa struttura dell'origine. Per maggiori informazioni, consulta l'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 integer Sì 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 string Lo stato attuale della traduzione. I possibili valori di stato sono: draft, queued, in_progress, completed, failed, out_of_credit e null.
completeness number La percentuale di stringhe tradotte (0–100). Calcolata come (completed_translatable_strings / total_translatable_strings) × 100.
Valori di stato
Stato Descrizione
draft Il file di origine è registrato ma non ha ancora alcun file allegato, quindi non c'è nulla da tradurre.
queued La traduzione è 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.
out_of_credit La traduzione si è interrotta perché il progetto ha esaurito le parole. Questo è uno stato finale: l'esecuzione non riprende da sola quando vengono aggiunte altre parole, quindi esegui il polling per questo stato come faresti per failed.
null Nessuna traduzione ha ancora raggiunto uno degli stati precedenti. Aspettati questo stato subito dopo aver creato una traduzione dei contenuti e trattalo come «non avviato» anziché come un errore.

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
}