تسجيل الدخول
AR AR
جرّب مجاناً
جدولة عرض توضيحي
تسجيل الدخول
AR AR

tp-sync-api

Документация API для интеграции переводов TranslatePress (TP Sync API)

Документация API для интеграции переводов TranslatePress (TP Sync API)

Этот API предоставляет два эндпоинта для работы со строками переводов в плагине TranslatePress. Базовый язык — английский (en_us). Все запросы требуют авторизации через Bearer-токен (получается в админке WordPress под меню "TP Sync").

Базовый URL: https://your-site.com/wp-json/tp-sync/v1/

1. Получение строк для перевода (GET /keys)

Этот эндпоинт возвращает список строк из словаря TranslatePress для указанного языка. Каждая строка включает ID (в формате dictionary:{id}), оригинальный текст на английском, текущий перевод, статус и метаданные пагинации. Сортировка по ID DESC (новые сверху). Даты created_at и updated_at всегда null (не запрашиваются в SQL).

Параметры запроса

Параметр Тип Обязательный Описание Значение по умолчанию
lang string Да Код языка (например, de для немецкого, fr для французского). Короткие коды нормализуются (de → de_de). —
page integer Нет Номер страницы для пагинации. 1
limit integer Нет Количество строк на странице (минимум 1, максимум 500). 100
updated_since string Нет Фильтр по дате обновления (ISO8601, например, 2025-10-01T00:00:00Z). Возвращает только строки, обновлённые после этой даты. —

Заголовки

  • Authorization: Bearer {токен} (обязательно)

Пример запроса (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"

Пример ответа (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"
  }
}

Описание полей в ответе

Поле Тип Описание
key_id string Уникальный ID строки: dictionary:{id} (id — номер записи в таблице wp_trp_dictionary_en_us_{lang}).
original string Оригинальный текст на английском.
translated string Текущий перевод для указанного языка (может быть пустым).
status integer Статус: 0 — не переведено, 1 — в процессе, 2 — переведено.
created_at string Дата создания (ISO8601, null — не запрашивается).
updated_at string Дата последнего обновления (ISO8601, null — не запрашивается).

Метаданные (meta)

  • total_count: Общее количество строк (с учётом фильтров).
  • page: Текущая страница.
  • limit: Лимит на страницу.
  • page_count: Общее количество страниц.
  • next_page: URL следующей страницы (null, если последняя).

Ошибки

  • 401: Отсутствует или неверный заголовок Authorization.
  • 403: Неверный токен.
  • 404: Язык не найден в TranslatePress (таблица отсутствует).

2. Обновление переводов (POST /translations)

Этот эндпоинт обновляет переводы для нескольких строк за раз (батч). Передаётся массив объектов с ID строки, языком и новым переводом. Обновляет статус на "переведено" (2) и поле updated_at.

Тело запроса (JSON)

Массив translations с объектами:

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

Параметры

Поле в объекте Тип Обязательный Описание
key_id string Да ID строки: dictionary:{id} (из GET /keys).
language_iso string Да Код языка (de → de_de, нормализуется автоматически).
translation string Да Новый текст перевода (сохраняется как есть).

Заголовки

  • Authorization: Bearer {токен} (обязательно)
  • Content-Type: application/json (обязательно)

Пример запроса (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"
      }
    ]
  }'

Пример ответа (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"
    }
  ]
}

Описание полей в ответе

  • translations: Массив успешно обновлённых переводов (возвращает входные данные + modified_at в ISO8601).
  • errors (опционально, если есть неудачи): Массив ошибок.
    • index: Индекс элемента в исходном массиве.
    • key_id: ID проблемной строки (если применимо).
    • error: Текст ошибки (примеры: "Missing required fields", "Invalid key_id format. Expected: dictionary:{id}", "Language not found", "Key not found in database", "Database update failed").

Ошибки

  • 400: Неверные данные (пустой/не-массив translations, отсутствие полей).
  • 401/403: Проблемы с авторизацией.
  • 404: Язык или ключ не найден (таблица/запись отсутствует).

Поддерживаемые языки

Короткие коды автоматически нормализуются (на основе маппинга в коде). Для неизвестных: {code}_{code} (например, 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

Получение токена

  • В админке WordPress: Меню TP Sync → Кнопка "Generate New Token" (токен 32 символа, генерируется автоматически при первом запуске).
  • Токен хранится в опции tp_sync_api_token.