Đăng nhập
VI VI
Dùng thử miễn phí
Lên lịch trình diễn demo
Đăng nhập
VI VI

tp-sync-api

Tài liệu API để tích hợp bản dịch TranslatePress (TP Sync API)

Tài liệu API để tích hợp bản dịch TranslatePress (TP Sync API)

Этот API предоставляет два эндпоинта для работы со строками переводов в плагине TranslatePress. Базовый язык — английский (en_us). Tất cả các yêu cầu đều cần được ủy quyền bằng token Bearer (được lấy trong trang quản trị WordPress dưới menu "TP Sync").

URL cơ sở: https://your-site.com/wp-json/tp-sync/v1/

1. Lấy chuỗi để dịch (GET /keys)

Endpoint này trả về danh sách chuỗi từ từ điển TranslatePress cho ngôn ngữ được chỉ định. Mỗi chuỗi bao gồm ID (ở định dạng, từ điển:{id}), văn bản gốc bằng tiếng Anh, bản dịch hiện tại, trạng thái và siêu dữ liệu phân trang. Sắp xếp theo ID DESC (mới nhất ở trên). Ngày, created_at và updated_at luôn null (không được yêu cầu trong SQL).

Tham số yêu cầu

Tham số, Loại Bắt buộc Mô tả Giá trị mặc định
lang chuỗi Có Код языка (например, de cho tiếng Đức, fr cho tiếng Pháp). Mã ngắn được chuẩn hóa (de → de_de). —
trang số nguyên Không Số trang để phân trang. 1
giới hạn số nguyên Không Số hàng trên mỗi trang (tối thiểu 1, tối đa 500). 100
updated_since chuỗi Không Фильтр по дате обновления (ISO8601, например, 2025-10-01T00:00:00Z). Chỉ trả về các hàng được cập nhật sau ngày này. —

Tiêu đề

  • Authorization: Bearer {токен} (bắt buộc)

Ví dụ yêu cầu (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"

Ví dụ về phản hồi (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"
  }
}

Mô tả các trường trong phản hồi

Trường Loại Mô tả
key_id chuỗi ID hàng duy nhất: từ điển:{id} id — số bản ghi trong bảng wp_trp_dictionary_en_us_{lang}).
gốc chuỗi Văn bản gốc bằng tiếng Anh.
đã dịch chuỗi Bản dịch hiện tại cho ngôn ngữ được chỉ định (có thể để trống).
trạng thái số nguyên Trạng thái: 0 — chưa dịch, 1 — đang xử lý, 2 — đã dịch.
created_at chuỗi Ngày tạo (ISO8601, null — không được yêu cầu).
updated_at chuỗi Дата последнего обновления (ISO8601, null — không được yêu cầu).

Siêu dữ liệu (meta)

  • total_count: Tổng số hàng (có tính đến bộ lọc).
  • trang: Trang hiện tại.
  • giới hạn: Giới hạn mỗi trang.
  • page_count=: Tổng số trang.
  • trang_tiếp_theo: URL следующей страницы (null, nếu là mục cuối cùng).

Lỗi

  • 401: Tiêu đề Authorization bị thiếu hoặc không hợp lệ.
  • 403: Mã thông báo không hợp lệ.
  • 404: Không tìm thấy ngôn ngữ trong TranslatePress (thiếu bảng).

2. Cập nhật bản dịch (POST /translations)

Endpoint này cập nhật bản dịch cho nhiều chuỗi cùng lúc (hàng loạt). Một mảng đối tượng có ID chuỗi, ngôn ngữ và bản dịch mới được truyền vào. Cập nhật trạng thái thành "đã dịch" (2) và trường, updated_at.

Nội dung yêu cầu (JSON)

Mảng bản dịch với đối tượng:

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

Cài đặt

Trường trong đối tượng, Loại Bắt buộc Mô tả
key_id chuỗi Có ID hàng: từ điển:{id} (từ GET /keys).
language_iso chuỗi Có Mã ngôn ngữ (de → de_de, được chuẩn hóa tự động).
Bản dịch chuỗi Có Новый текст перевода (сохраняется как есть).

Tiêu đề

  • Authorization: Bearer {токен} (bắt buộc)
  • Content-Type: application/json (bắt buộc)

Ví dụ yêu cầu (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"
      }
    ]
  }'

Ví dụ về phản hồi (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": "Không tìm thấy khóa trong cơ sở dữ liệu"
    }
  ]
}

Mô tả các trường trong phản hồi

  • bản dịch: Mảng các bản dịch đã được cập nhật thành công (trả về dữ liệu đầu vào + modified_at theo ISO8601).
  • lỗi (tùy chọn, nếu có lỗi): Mảng lỗi.
    • chỉ mục: Chỉ mục của phần tử trong mảng nguồn.
    • key_id: ID của dòng có vấn đề (nếu áp dụng).
    • lỗi: Văn bản lỗi (ví dụ: "Thiếu các trường bắt buộc", "Định dạng key_id không hợp lệ. Dự kiến: dictionary:{id}", "Không tìm thấy ngôn ngữ", "Không tìm thấy khóa trong cơ sở dữ liệu", "Cập nhật cơ sở dữ liệu không thành công").

Lỗi

  • 400: Неверные данные (пустой/не-массив bản dịch, không có trường).
  • 401/403: Sự cố ủy quyền.
  • 404: Không tìm thấy ngôn ngữ hoặc khóa (bảng/bản ghi không tồn tại).

Ngôn ngữ được hỗ trợ

Các mã ngắn được tự động chuẩn hóa (dựa trên ánh xạ trong mã). Đối với các mã không xác định:, {code}_{code} (ví dụ, 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

Lấy mã thông báo

  • Trong trang quản trị WordPress: Menu, Đồng bộ hóa TP → Nút "Tạo token mới" (token 32 ký tự, được tạo tự động khi khởi chạy lần đầu).
  • Mã thông báo được lưu trữ trong tùy chọn, tp_sync_api_token.