Переводы
Эндпоинты группы переводов страницы — с параметрами, ответами и кодами отказов; как переводить сайт по шагам, написано на странице «Языки и переводы».
Во всех примерах API — https://onpress.pro/api/v2, SITE — id сайта (SITE_ID), OP_TOKEN — токен op_XXXX.
Группа переводов — страницы одного содержания на разных языках: из неё строятся hreflang и переключатель языков. Эндпоинты — под $API/site/$SITE/pages/{ref}/translations, {ref} — id, слаг или путь с ~ вместо / (ru~o-nas). На сайте, где не заведено ни одного языка, все четыре отвечают 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": []
}| Поле | Смысл |
|---|---|
page | страница из адреса: id, lang, title |
translations | {язык: id}; всегда содержит саму страницу под её языком, даже вне группы |
pages | по странице группы: id, title, status, url с префиксом языка, link (null у неопубликованной) |
missing_languages | языки сайта, на которых перевода нет |
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
polylang_inactive | 409 | у сайта нет языков | добавьте язык: PATCH /data/site.languages |
page_not_found | 404 | страницы нет | проверьте {ref} |
ambiguous_page | 409 | слаг у нескольких страниц | назовите страницу id или путём |
PUT /pages/{ref}/translations
Кладёт группу целиком: карта и есть группа, кто был в группе и отсутствует в карте — выходит из неё (unlinked). Страница из адреса всегда участник под своим языком, её можно не указывать. Например, связать английскую страницу 6444 с русской:
| Поле | Тип | По умолчанию | Описание |
|---|---|---|---|
translations | object | — | обязательно; {язык: ссылка}, ссылка — id, слаг или путь; null, "", 0 — «на этом языке страницы нет» |
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.created — группа заведена этим запросом, deleted_groups — группы, которые опустели от переноса страниц и удалены. Голый слаг в карте ищется среди страниц своего языка. Все отказы translations_rejected собираются за один проход, чтобы карту можно было исправить за один заход.
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
bad_translations | 400 | translations не объект | пришлите {"en": 12, "ru": "/ru/o-nas/"} |
translations_rejected | 409 | в карте неизвестный язык, несуществующая страница, страница другого языка, одна страница дважды или чужая страница под языком страницы из адреса; rejected: [{lang, ref, reason}] | исправьте строки из rejected, ничего не записано |
page_in_other_group | 409 | страница уже в другой группе; its_group, target_group | выведите её из группы DELETE /pages/{ref}/translations |
page_has_no_language | 409 | у страницы из адреса нет языка | проставьте язык: POST /pages/language |
polylang_inactive | 409 | у сайта нет языков | добавьте язык: PATCH /data/site.languages |
POST /pages/{ref}/translations/{lang}
Добавляет один перевод и сохраняет остальных участников группы; прежний перевод этого языка выходит из группы (unlinked). Например, привязать к странице 6444 русскую страницу 6445:
| Поле | Тип | По умолчанию | Описание |
|---|---|---|---|
page | number, string | — | обязательно; перевод: id, слаг или путь. Слаг ищется среди страниц языка {lang} |
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 },
"pages": { "en": { "id": 6444, "…": "…" }, "ru": { "id": 6445, "…": "…" } },
"changed": true,
"group": { "term_id": 172, "created": false },
"unlinked": [],
"deleted_groups": [],
"content_saved": [6444, 6445]
}| Код | HTTP | Когда | Что делать |
|---|---|---|---|
page_required | 400 | нет page | передайте ссылку на перевод |
unknown_language | 422 | языка {lang} нет на сайте | возьмите язык из GET /data/site.languages |
same_language | 409 | {lang} — язык самой страницы | назовите язык перевода |
page_language_mismatch | 409 | перевод на другом языке; actual_lang | проставьте ему язык или возьмите другую страницу |
page_in_other_group | 409 | перевод уже в другой группе | сначала DELETE /pages/{ref}/translations для него |
page_has_no_language | 409 | у страницы из адреса нет языка | проставьте язык: POST /pages/language |
page_not_found | 404 | страницы из адреса или перевода нет | проверьте ссылки |
ambiguous_page | 409 | слаг у нескольких страниц | назовите страницу id или путём |
polylang_inactive | 409 | у сайта нет языков | добавьте язык: PATCH /data/site.languages |
DELETE /pages/{ref}/translations
Выводит страницу из группы; страница остаётся опубликованной со своим языком. Группа без страниц удаляется (group_deleted: true), группа из одной страницы остаётся. Например, вывести русскую страницу 6445:
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]
}Страница вне группы отвечает unlinked: false, changed: false, remaining: {}.
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
page_not_found | 404 | страницы нет | проверьте {ref} |
ambiguous_page | 409 | слаг у нескольких страниц | назовите страницу id или путём |
polylang_inactive | 409 | у сайта нет языков | добавьте язык: PATCH /data/site.languages |
Перевод при публикации
POST /pages/markdown связывает перевод с оригиналом сразу при публикации: со свойством translation_of эндпоинт пишет страницу и ставит ее в группу в одной транзакции. Правила и отказы — в разделе «Опубликовать или обновить» справочника страниц; страница вместе с её данными и меню переводится одним запросом POST /pages/import.