用于集成 TranslatePress 翻译的 API 文档 (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（格式为, 字典:{id}), 英文原文, 当前翻译, 状态和分页元数据. 按 ID DESC 排序 (新的在上方). 日期, created_at 和 updated_at 始终 null (不会在 SQL 中请求).

请求参数

参数，	类型	必填	描述	默认值
lang	字符串	是	Код языка (например, de 用于德语, fr 用于法语). 短代码会被规范化 (de → de_de).	—
页面	整数	否	用于分页的页码.	1
限制	整数	否	每页行数 (最小值 1，最大值 500).	100
updated_since	字符串	否	Фильтр по дате обновления (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	字符串	唯一行 ID: 字典:{id} id — 表中的记录编号 wp_trp_dictionary_en_us_{lang}).
原始	字符串	英文原文.
已翻译	字符串	指定语言的当前翻译（可以为空）。
状态	整数	状态: 0 — 未翻译, 1 — 进行中, 2 — 已翻译.
created_at	字符串	创建日期 (ISO8601, null — 未请求).
updated_at	字符串	Дата последнего обновления (ISO8601, null — 未请求).

元数据 (meta)

• total_count: 总行数（考虑筛选器）。
• 页面: 当前页面.
• 限制: 每页限制.
• page_count=: 总页数.
• 下一_页: URL следующей страницы (null, 如果是最后一个).

错误

• 401: 缺少 Authorization 标头或标头无效.
• 403: 令牌无效.
• 404: 在 TranslatePress 中未找到语言 (表缺失).

2. 更新翻译 (POST /translations)

此端点会一次更新多个字符串的翻译（批量）。传入一个对象数组，其中包含字符串 ID、语言和新翻译。将状态更新为"已翻译" (2) 和字段, updated_at.

请求正文 (JSON)

数组 翻译 包含对象:

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

设置

对象中的字段,	类型	必填	描述
key_id	字符串	是	行 ID: 字典:{id} (来自 GET /keys).
language_iso	字符串	是	语言代码 (de → de_de, 自动规范化).
翻译	字符串	是	Новый текст перевода (сохраняется как есть).

标题

• 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"
    }
  ]
}

响应中字段的说明

• 翻译: 成功更新的翻译数组（返回输入数据 + modified_at 以 ISO8601 格式).
• 错误 (可选, 如果存在失败): 错误数组.
  • 索引: 源数组中元素的索引.
  • key_id: 有问题的行的 ID (如适用).
  • 错误: 错误文本 (示例: "缺少必填字段", "key_id 格式无效。预期格式: dictionary:{id}", "未找到语言", "数据库中未找到键", "数据库更新失败").

错误

• 400: Неверные данные (пустой/не-массив 翻译, 缺少字段).
• 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 同步 → “生成新令牌”按钮 (32 个字符的令牌, 首次启动时自动生成).
• 令牌存储在选项中, tp_sync_api_token.