Справочник: переводы

Группа переводов — страницы одного содержания на разных языках. Из неё строятся hreflang и переключатель языков. Ручки — под $API/site/$SITE/pages/{ref}/translations; {ref} — id, слаг или путь с тильдами (ru~o-nas). На сайте без Polylang все отвечают 409 polylang_inactive. Все проверки идут до записи, неудачная не пишет ничего. После изменения группы каждая затронутая страница (и выпавшая) получает событие обновления — пересобираются hreflang и её кэш; их id — в content_saved. Как переводить страницы — переводы.

GET /pages/{ref}/translations

curl -s -H "Authorization: Bearer $OP_TOKEN" "$API/site/$SITE/pages/6428/translations"

{
  "success": true,
  "site_id": "x9HTLHECq",
  "page": { "id": 6428, "lang": "en", "title": "Проба API" },
  "translations": { "en": 6428, "ru": 6431 },
  "pages": {
    "en": { "id": 6428, "title": "Проба API", "status": "publish", "url": "/proba-api/", "link": "https://test.onpress.pro/proba-api/" },
    "ru": { "id": 6431, "title": "Проба API по-русски", "status": "publish", "url": "/ru/proba-api/", "link": "https://test.onpress.pro/ru/proba-api/" }
  },
  "missing_languages": []
}

translations всегда содержит саму страницу под её языком. missing_languages — языки сайта, на которых перевода нет.

PUT /pages/{ref}/translations

Положить группу целиком.

Поле	Тип	Смысл
translations	object	{язык: ссылка} — id, слаг или путь; null, "", 0 — «нет страницы на этом языке»

Карта и есть группа: кто был и отсутствует — выходит (unlinked). Страница из адреса — всегда участник под своим языком, её можно не указывать.

curl -s -X PUT "$API/site/$SITE/pages/6444/translations" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"translations": {"en": 6444, "ru": "/ru/docs-tr-proba/"}}'

{
  "success": true,
  "site_id": "x9HTLHECq",
  "page": { "id": 6444 },
  "translations": { "en": 6444, "ru": 6445 },
  "pages": { "en": { "id": 6444, "…": "…" }, "ru": { "id": 6445, "…": "…" } },
  "changed": true,
  "group": { "term_id": 172, "created": true },
  "unlinked": [],
  "deleted_groups": [],
  "content_saved": [6444, 6445]
}

Повтор той же карты — changed: false, group.term_id: null, ничего не пишется. deleted_groups — группы, которые опустели от переноса и удалены.

Отказы: 400 bad_translations (не объект), 409 translations_rejected (rejected: [{lang, ref, reason}] — неизвестный язык, нет страницы, язык страницы не совпадает с ключом, одна страница дважды, чужая страница под языком страницы из адреса), 409 page_in_other_group (its_group, target_group — сначала выведите страницу из её группы), 409 page_has_no_language.

POST /pages/{ref}/translations/{lang}

Добавить один перевод, сохранив остальных.

Поле	Смысл
page	перевод: id, слаг или путь

curl -s -X POST "$API/site/$SITE/pages/6444/translations/ru" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"page": 6445}'

{
  "success": true,
  "site_id": "x9HTLHECq",
  "page": { "id": 6444 },
  "linked": { "lang": "ru", "id": 6445 },
  "translations": { "en": 6444, "ru": 6445 },
  "changed": true,
  "group": { "term_id": 172, "created": false },
  "unlinked": [],
  "deleted_groups": [],
  "content_saved": [6444, 6445]
}

Прежний перевод этого языка выходит из группы (unlinked). Отказы: 400 page_required, 422 unknown_language, 409 same_language ({lang} — язык самой страницы), 409 page_language_mismatch (actual_lang), 409 page_in_other_group.

DELETE /pages/{ref}/translations

Вывести страницу из группы. Страница остаётся опубликованной со своим языком.

curl -s -X DELETE "$API/site/$SITE/pages/6445/translations" -H "Authorization: Bearer $OP_TOKEN"

{
  "success": true,
  "site_id": "x9HTLHECq",
  "page": { "id": 6445 },
  "was_in": { "ru": 6445, "en": 6444 },
  "remaining": { "en": 6444 },
  "unlinked": true,
  "changed": true,
  "group_deleted": false,
  "content_saved": [6445, 6444]
}

Группа без страниц удаляется (group_deleted: true), группа из одной страницы остаётся. Страница вне группы — unlinked: false, changed: false.

translation_of при публикации

Перевод можно связать сразу при публикации полем translation_of во frontmatter POST /pages/markdown — в той же транзакции, что и запись. Правила и отказы — в справочнике страниц и в переводах.