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

Этот API предоставляет два эндпоинта для работы со строками переводов в плагине TranslatePress. Базовый язык — английский (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. Récupération des chaînes à 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 inclut 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, created_at et updated_at toujours null (ne sont pas demandés dans SQL).

Paramètres de la requête

Paramètre,	Type	Obligatoire	Description	Valeur par défaut
lang	chaîne	Oui	Код языка (например, 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
updated_since	chaîne	Non	Фильтр по дате обновления (ISO8601, например, 2025-10-01T00:00:00Z). Renvoie uniquement les lignes mises à jour après cette date.	—

En-têtes

• Authorization: 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": "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"
  }
}

Description des champs dans la réponse

Champ	Type	Description
key_id	chaîne	ID de ligne unique: 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 indiquée (peut être vide).
statut	entier	Statut: 0 — non traduit, 1 — en cours, 2 — traduit.
created_at	chaîne	Date de création (ISO8601, null — non demandé).
updated_at	chaîne	Дата последнего обновления (ISO8601, null — non demandé).

Métadonnées (meta)

• total_count: Nombre total de lignes (en tenant compte des filtres).
• page: Page actuelle.
• limite: Limite par page.
• page_count=: Nombre total de pages.
• page_suivante: URL следующей страницы (null, si c’est la dernière).

Erreurs

• 401: En-tête Authorization manquant ou non valide.
• 403: Jeton non valide.
• 404: Langue introuvable dans TranslatePress (table manquante).

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

Cet endpoint met à jour les traductions de plusieurs chaînes à la fois (lot). Un tableau d’objets avec l’ID de la chaîne, la langue et la nouvelle traduction est transmis. Met à jour le statut en "traduit" (2) et le champ, updated_at.

Corps de la requête (JSON)

Tableau traductions avec des objets:

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

Paramètres

Champ dans l’objet,	Type	Obligatoire	Description
key_id	chaîne	Oui	ID de ligne: dictionnaire:{id} (depuis GET /keys).
language_iso	chaîne	Oui	Code de langue (de → de_de, normalisé automatiquement).
Traduction	chaîne	Oui	Новый текст перевода (сохраняется как есть).

En-têtes

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

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

Description des champs dans la réponse

• traductions: Tableau des traductions mises à jour avec succès (renvoie les données d’entrée + modified_at au format ISO8601).
• erreurs (facultatif, en cas d’échecs): Tableau d’erreurs.
  • index: Index de l’élément dans le tableau source.
  • key_id: ID de la ligne problématique (le cas échéant).
  • erreur: Texte de l’erreur (exemples: "Champs obligatoires manquants", "Format key_id non valide. Attendu: dictionary:{id}", "Langue introuvable", "Clé introuvable dans la base de données", "Échec de la mise à jour de la base de données").

Erreurs

• 400: Неверные данные (пустой/не-массив 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
• 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

Obtention du jeton

• Dans l’interface d’administration WordPress: Menu, Synchronisation TP → Bouton "Générer un nouveau jeton" (jeton de 32 caractères, généré automatiquement au premier lancement).
• Le jeton est stocké dans l’option, tp_sync_api_token.