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

Этот API предоставляет два эндпоинта для работы со строками переводов в плагине TranslatePress. Базовый язык — английский (en_us). Tutte le richieste richiedono l’autorizzazione tramite token Bearer (si ottiene nell’admin di WordPress nel menu "TP Sync").

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

1. Recupero delle stringhe da tradurre (GET /keys)

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

Parametri della richiesta

Parametro,	Tipo	Obbligatorio	Descrizione	Valore predefinito
lang	stringa	Sì	Код языка (например, de per il tedesco, fr per il francese). I codici brevi vengono normalizzati (de → de_de).	—
pagina	numero intero	No	Numero di pagina per la paginazione.	1
limite	numero intero	No	Numero di righe per pagina (minimo 1, massimo 500).	100
updated_since	stringa	No	Фильтр по дате обновления (ISO8601, например, 2025-10-01T00:00:00Z). Restituisce solo le righe aggiornate dopo questa data.	—

Intestazioni

• Authorization: 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": "Hallo Welt",
      "status": 2,
      "created_at": null,
      "updated_at": null
    },
    {
      "key_id": "dictionary:124",
      "original": "Welcome",
      "translated": "",
      "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
key_id	stringa	ID riga univoco: dizionario:{id} id — numero del record nella tabella wp_trp_dictionary_en_us_{lang}).
originale	stringa	Testo originale in inglese.
tradotto	stringa	Traduzione corrente per la lingua specificata (può essere vuota).
stato	numero intero	Stato: 0 — non tradotto, 1 — in corso, 2 — tradotto.
created_at	stringa	Data di creazione (ISO8601, null — non richiesto).
updated_at	stringa	Дата последнего обновления (ISO8601, null — non richiesto).

Metadati (meta)

• total_count: Numero totale di righe (tenendo conto dei filtri).
• pagina: Pagina corrente.
• limite: Limite per pagina.
• page_count=: Numero totale di pagine.
• pagina_successiva: URL следующей страницы (null, se è l’ultima).

Errori

• 401: Intestazione Authorization mancante o non valida.
• 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ù stringhe alla volta (batch). Viene passato un array di oggetti con l’ID della stringa, la lingua e la nuova traduzione. Aggiorna lo stato a "tradotto" (2) e il campo, updated_at.

Corpo della richiesta (JSON)

Array traduzioni con oggetti:

{
  "translations": [
    {
      "key_id": "dictionary:123",
      "language_iso": "de",
      "translation": "Hallo Welt"
    },
    {
      "key_id": "dictionary:124",
      "language_iso": "de",
      "translation": "Willkommen"
    }
  ]
}

Impostazioni

Campo nell'oggetto,	Tipo	Obbligatorio	Descrizione
key_id	stringa	Sì	ID riga: dizionario:{id} (da GET /keys).
language_iso	stringa	Sì	Codice lingua (de → de_de, normalizzato automaticamente).
Traduzione	stringa	Sì	Новый текст перевода (сохраняется как есть).

Intestazioni

• Authorization: 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": "Hallo Welt"
      }
    ]
  }'

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": "Key not found in database"
    }
  ]
}

Descrizione dei campi nella risposta

• traduzioni: Array di traduzioni aggiornate correttamente (restituisce i dati di input + modified_at in ISO8601).
• errori (opzionale, se sono presenti errori): Array di errori.
  • indice: Indice dell'elemento nell'array di origine.
  • key_id: ID della riga problematica (se applicabile).
  • errore: Testo dell’errore (esempi: "Campi obbligatori mancanti", "Formato key_id non valido. Previsto: dictionary:{id}", "Lingua non trovata", "Chiave non trovata nel database", "Aggiornamento del database non riuscito").

Errori

• 400: Неверные данные (пустой/не-массив 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 (in base alla mappatura nel codice). Per quelli sconosciuti:, {code}_{code} (ad esempio, pl → pl_pl).

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

Ottenimento del token

• Nell’area di amministrazione di WordPress: Menu, Sincronizzazione TP → Pulsante "Genera nuovo token" (token di 32 caratteri, generato automaticamente al primo avvio).
• Il token è archiviato nell'opzione, tp_sync_api_token.