Documentation API pour l'intégration des traductions TranslatePress (TP Sync API)

Cette API fournit deux points de terminaison pour travailler avec les chaînes de traduction dans le plugin TranslatePress. La langue de base est l'anglais (en_us). Toutes les requêtes nécessitent une autorisation via un jeton Bearer (obtenu dans l'administration WordPress sous le menu « TP Sync »).

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

1. Obtention des lignes à traduire (GET /keys)

Ce point de terminaison renvoie une liste de chaînes du dictionnaire TranslatePress pour la langue spécifiée. Chaque chaîne comprend un ID (au format dictionnaire : {id}), texte original en anglais, traduction actuelle, statut et métadonnées de pagination. Tri par ID DESC (les plus récents en haut). Dates, créé le et mis à jour le toujours null (ne sont pas demandés en SQL).

Paramètres de la requête

Paramètre	Type	Obligatoire	Description	Valeur par défaut
lang	chaîne	Oui	Code de langue (par exemple, de pour l'allemand fr pour le français). Les codes courts sont normalisés (de → de_de).	—
page	entier	Non	Numéro de page pour la pagination.	1
limite	entier	Non	Nombre de lignes par page (minimum 1, maximum 500).	100
mis à jour depuis	chaîne	Non	Filtre par date de mise à jour (ISO8601, par exemple,) 2025-10-01T00:00:00Z). Retourne uniquement les lignes mises à jour après cette date.	—

Titres

• Autorisation : Bearer {токен} (obligatoire)

Exemple de requête (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"

Exemple de réponse (JSON)

{
  "keys": [
    {
      "key_id": "dictionary:123",
      "original": "Hello World",
      "translated": "Bonjour le monde",
      "status": 2,
      "created_at": null,
      "updated_at": null
    },
    {
      "key_id": "dictionary:124",
      "original": "Welcome",
      "translated": "Bienvenue",
      "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"
  }
}

Description des champs dans la réponse

Champ	Type	Description
clé_id	chaîne	ID unique de la ligne : dictionnaire : {id} (id — numéro d'enregistrement dans le tableau wp_trp_dictionary_en_us_{lang}).
original	chaîne	Texte original en anglais.
traduit	chaîne	Traduction actuelle pour la langue spécifiée (peut être vide).
statut	entier	Statut : 0 — non traduit, 1 — en cours, 2 — traduit.
créé le	chaîne	Date de création (ISO8601 null — non demandé).
mis à jour le	chaîne	Date de la dernière mise à jour (ISO8601 null — non demandé).

Métadonnéesmeta)

• total_countNombre total de lignes (y compris les filtres).
• pagePage actuelle.
• limiteLimite par page.
• nombre de pagesNombre total de pages.
• page suivante: URL de la page suivantenull, si le dernier).

Erreurs

• 401 : En-tête Authorization absent ou incorrect.
• 403 : Jeton invalide.
• 404 : Langue non trouvée dans TranslatePress (tableau manquant).

2. Mise à jour des traductions (POST /translations)

Ce point de terminaison met à jour les traductions pour plusieurs lignes à la fois (lot). Un tableau d'objets avec l'ID de la ligne, la langue et la nouvelle traduction est transmis. Met à jour le statut à "traduit" (2) et le champ mis à jour le.

Corps de la requête (JSON)

Tableau traductions avec des objets :

{
  "translations": [
    {
      "key_id": "dictionary:123",
      "language_iso": "de",
      "translation": "Bonjour le monde"
    },
    {
      "key_id": "dictionary:124",
      "language_iso": "de",
      "translation": "Bienvenue"
    }
  ]
}

Paramètres

Champ dans l'objet	Type	Obligatoire	Description
clé_id	chaîne	Oui	ID de la ligne : dictionnaire : {id} (depuis GET /keys).
code_iso_langue	chaîne	Oui	Code de langue (de → de_de, normalisé automatiquement).
traduction	chaîne	Oui	Nouveau texte de traduction (conservé tel quel).

Titres

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

Exemple de requête (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": "Bonjour le monde"
      }
    ]
  }'

Exemple de réponse (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": "Clé introuvable dans la base de données"
    }
  ]
}

Description des champs dans la réponse

• traductionsTableau des traductions mises à jour avec succès (renvoie les données d'entrée + modifié le en ISO8601).
• erreurs (facultatif, en cas d'échecs) : Tableau des erreurs.
  • indexIndice de l’élément dans le tableau d’origine.
  • clé_id: ID de la ligne problématique (le cas échéant).
  • erreurTexte d'erreur (exemples : « Champs requis manquants », « Format de key_id invalide. Attendu : dictionary:{id} », « Langue non trouvée », « Clé non trouvée dans la base de données », « Échec de la mise à jour de la base de données »).

Erreurs

• 400 : Données incorrectes (vide/pas un tableau) traductions, absence de champs).
• 401/403 : Problèmes d'autorisation.
• 404 : Langue ou clé introuvable (table/enregistrement absent).

Langues prises en charge

Les codes courts sont automatiquement normalisés (sur la base du mappage dans le code). Pour les inconnus : {code}_{code} (par exemple, pl → pl_pl).

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

Obtention du jeton

• Dans l'administration WordPress : Menu Synchronisation TP → Bouton « Generate New Token » (jeton de 32 caractères, généré automatiquement lors du premier lancement).
• Le jeton est stocké dans l'option jeton_api_de_sync_tp.