Documentazione API per l'integrazione delle traduzioni TranslatePress (TP Sync API)

Questa API fornisce due endpoint per lavorare con le stringhe di traduzione nel plugin TranslatePress. La lingua base è l'inglese (en_us). Tutte le richieste richiedono l'autorizzazione tramite token Bearer (ottenuto nell'area amministrativa di WordPress sotto il menu "TP Sync").

URL di base: https://your-site.com/wp-json/tp-sync/v1/

1. Ottenere le righe da tradurre (GET /keys)

Questo endpoint restituisce un elenco di stringhe dal dizionario TranslatePress per la lingua specificata. Ogni stringa include un ID (nel formato dizionario: {id}), testo originale in inglese, traduzione corrente, stato e metadati di paginazione. Ordinamento per ID DESC (i più recenti in cima). Date, creato il e aggiornato il sempre null (non richiesti in SQL).

Parametri della richiesta

Parametro	Tipo	Obbligatorio	Descrizione	Valore predefinito
lang	stringa	Sì	Codice lingua (ad esempio, de per il tedesco fr per il francese). I codici brevi vengono normalizzati (de → de_de).	—
pagina	intero	No	Numero di pagina per la paginazione.	1
limite	intero	No	Numero di righe per pagina (minimo 1, massimo 500).	100
aggiornato da	stringa	No	Filtro per data di aggiornamento (ISO8601, ad esempio,) 2025-10-01T00:00:00Z). Restituisce solo le righe aggiornate dopo questa data.	—

Intestazioni

• Autorizzazione: Bearer {токен} (obbligatorio)

Esempio di richiesta (cURL)

curl -X GET "https://your-site.com/wp-json/tp-sync/v1/keys?lang=de&page=1&limit=50&updated_since=2025-10-01T00:00:00Z" \
  -H "Authorization: Bearer your-api-token-here"

Esempio di risposta (JSON)

{
  "keys": [
    {
      "key_id": "dictionary:123",
      "original": "Hello World",
      "translated": "Ciao Mondo",
      "status": 2,
      "created_at": null,
      "updated_at": null
    },
    {
      "key_id": "dictionary:124",
      "original": "Welcome",
      "translated": "Benvenuto",
      "status": 0,
      "created_at": null,
      "updated_at": null
    }
  ],
  "meta": {
    "total_count": 150,
    "page": 1,
    "limit": 50,
    "page_count": 3,
    "next_page": "https://your-site.com/wp-json/tp-sync/v1/keys?lang=de&page=2&limit=50&updated_since=2025-10-01T00:00:00Z"
  }
}

Descrizione dei campi nella risposta

Campo	Tipo	Descrizione
chiave_id	stringa	ID univoco della riga: dizionario: {id} (id — numero della voce nella tabella wp_trp_dictionary_en_us_{lang}).
originale	stringa	Testo originale in inglese.
tradotto	stringa	Traduzione corrente per la lingua indicata (può essere vuota).
stato	intero	Stato: 0 — non tradotto, 1 — in corso, 2 — tradotto.
creato il	stringa	Data di creazione (ISO8601 null — non richiesto).
aggiornato il	stringa	Data dell'ultimo aggiornamento (ISO8601 null — non richiesto).

Metadatimeta)

• total_countNumero totale di righe (inclusi i filtri).
• paginaPagina corrente.
• limiteLimite per pagina.
• numero di pagineNumero totale di pagine.
• pagina successiva: URL della pagina successivanull, se l'ultimo).

Errori

• 401: Header Authorization mancante o non valido.
• 403: Token non valido.
• 404: Lingua non trovata in TranslatePress (tabella mancante).

2. Aggiornamento delle traduzioni (POST /translations)

Questo endpoint aggiorna le traduzioni per più righe contemporaneamente (batch). Viene passato un array di oggetti con l'ID della riga, la lingua e la nuova traduzione. Aggiorna lo stato a "tradotto" (2) e il campo aggiornato il.

Corpo della richiesta (JSON)

Array traduzioni con oggetti:

{
  "translations": [
    {
      "key_id": "dictionary:123",
      "language_iso": "de",
      "translation": "Ciao mondo"
    },
    {
      "key_id": "dictionary:124",
      "language_iso": "de",
      "translation": "Benvenuto"
    }
  ]
}

Parametri

Campo nell'oggetto	Tipo	Obbligatorio	Descrizione
chiave_id	stringa	Sì	ID della riga: dizionario: {id} (da GET /keys).
codice_iso_lingua	stringa	Sì	Codice lingua (de → de_de, normalizzato automaticamente).
traduzione	stringa	Sì	Nuovo testo di traduzione (mantenuto così com'è).

Intestazioni

• Autorizzazione: Bearer {токен} (obbligatorio)
• Content-Type: application/json (obbligatorio)

Esempio di richiesta (cURL)

curl -X POST "https://your-site.com/wp-json/tp-sync/v1/translations" \
  -H "Authorization: Bearer your-api-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "translations": [
      {
        "key_id": "dictionary:123",
        "language_iso": "de",
        "translation": "Ciao mondo"
      }
    ]
  }'

Esempio di risposta (JSON)

{
  "translations": [
    {
      "key_id": "dictionary:123",
      "language_iso": "de",
      "translation": "Hallo Welt",
      "modified_at": "2025-10-15T12:00:00Z"
    }
  ],
  "errors": [
    {
      "index": 1,
      "key_id": "dictionary:999",
      "error": "Chiave non trovata nel database"
    }
  ]
}

Descrizione dei campi nella risposta

• traduzioniArray di traduzioni aggiornate con successo (restituisce i dati di input + modificato il in ISO8601).
• errori (opzionale, se ci sono fallimenti): Array di errori.
  • indiceIndice dell'elemento nell'array originale.
  • chiave_id: ID della riga problematica (se applicabile).
  • erroreTesto dell'errore (esempi: "Campi obbligatori mancanti", "Formato key_id non valido. Previsto: dictionary:{id}", "Lingua non trovata", "Chiave non trovata nel database", "Aggiornamento database non riuscito").

Errori

• 400: Dati non validi (vuoto/non array) traduzioni, assenza di campi).
• 401/403: Problemi di autorizzazione.
• 404: Lingua o chiave non trovata (tabella/record assente).

Lingue supportate

I codici brevi vengono normalizzati automaticamente (basandosi sul mapping nel codice). Per quelli sconosciuti: {code}_{code} (ad esempio, pl → pl_pl).

• en → en_us
• a
• id → id_id
• ko → ko_kr
• tr → tr_tr
• vi → vi
• ru → ru_ru
• fr → fr_fr
• de → de_de
• it → it_it
• a
• pt → pt_pt
• zh → zh_cn
• es → es_es

Ottenimento del token

• Nell'admin di WordPress: Menu Sincronizzazione TP → Pulsante "Generate New Token" (token di 32 caratteri, generato automaticamente al primo avvio).
• Il token è memorizzato nell'opzione token_api_di_sync_tp.