Языки

Эндпоинты языков сайта: список, каталог языков, добавление, правка, основной язык, удаление и настройки адресов; как языки и переводы устроены для человека — на странице Языки и переводы.

Во всех примерах API — https://onpress.pro/api/v2, SITE — id сайта (SITE_ID), OP_TOKEN — токен op_XXXX. Права на всех эндпоинтах страницы — администратор сайта. Как выбирается сайт и в какой форме приходят отказы — Доступ и токен.

GET /data/site.languages

Отдаёт языки сайта — системные данные site.languages, по записи на язык. Например, прочитать все языки:

curl -s -H "Authorization: Bearer $OP_TOKEN" "$API/site/$SITE/data/site.languages"

{
  "success": true,
  "site_id": "x9HTLHECq",
  "name": "site.languages",
  "origin": "system",
  "writable": true,
  "write": { "method": "PATCH", "at": "/data/site.languages", "dry_run": true, "…": "…" },
  "total": 2,
  "items": [
    { "slug": "en", "name": "English", "locale": "en_US", "flag": "us", "rtl": false, "order": 0, "is_default": true, "url": "https://test.onpress.pro/", "front_page": 5776, "count": 46 },
    { "slug": "ru", "name": "Русский", "locale": "ru_RU", "flag": "ru", "rtl": false, "order": 0, "is_default": false, "url": "https://test.onpress.pro/ru/", "front_page": 6037, "count": 38 }
  ]
}

Параметр	Тип	По умолчанию	Описание
`match`	JSON	—	фильтр по полям: `{"slug":"ru"}` — один язык

Поле	Тип	Описание
`slug`	string	слаг языка, он же префикс в адресе
`name`	string	название в переключателе языков
`locale`	string	локаль: `ru_RU`, `en_US`
`flag`	string	код флага
`rtl`	bool	письмо справа налево
`order`	number	место в переключателе
`is_default`	bool	основной язык сайта
`url`	string	адрес главной языка
`front_page`	number или null	id главной страницы языка
`count`	number	сколько материалов на языке

GET /data/site.locales

Отдаёт каталог языков, которые можно добавить на сайт, — по названию, только чтение. Например:

curl -s -H "Authorization: Bearer $OP_TOKEN" "$API/site/$SITE/data/site.locales"

{
  "success": true,
  "site_id": "x9HTLHECq",
  "name": "site.locales",
  "origin": "system",
  "writable": false,
  "total": 136,
  "items": [
    { "locale": "so_SO", "slug": "so", "name": "Af-Soomaali", "flag": "so", "rtl": false, "added": false },
    { "locale": "af", "slug": "af", "name": "Afrikaans", "flag": "za", "rtl": false, "added": false },
    { "locale": "en_US", "slug": "en", "name": "English", "flag": "us", "rtl": false, "added": true }
  ]
}

Поля: locale, slug, name — название на самом языке, flag, rtl и added — язык уже есть на сайте. У двух локалей бывает один слаг (en_US и en_GB — оба en): вторую на сайт с первой добавляйте со своим slug. Запись в site.locales отвечает 409 computed_source: язык из каталога добавляет append.

PATCH /data/site.languages

Добавляет, меняет, делает основным и удаляет языки списком правок patch — за раз сколько угодно. Например, добавить немецкий и сразу поменять ему название и флаг:

curl -s -X PATCH "$API/site/$SITE/data/site.languages" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"patch": [{"action": "append", "item": {"locale": "de_DE"}}, {"action": "merge", "match": {"slug": "de"}, "fields": {"name": "Deutsch (AT)", "flag": "at"}}]}'

{
  "success": true,
  "site_id": "x9HTLHECq",
  "applied": true,
  "operations": [
    { "index": 0, "action": "append", "slug": "de", "changed": true },
    { "index": 1, "action": "merge", "slug": "de", "changed": true, "fields": ["name", "flag"] }
  ],
  "default": "en",
  "settings": { "force_lang": 1, "hide_default": true, "…": "…" },
  "languages": [ { "slug": "en", "…": "…" }, { "slug": "ru", "…": "…" }, { "slug": "de", "name": "Deutsch (AT)", "flag": "at", "front_page": null, "…": "…" } ],
  "source": "site.languages",
  "rebaked": { "status": "started", "reason": "the frames that print languages are baked again in the background, within a minute or two" }
}

Поле	Тип	По умолчанию	Описание
`patch`	array	—	правки по порядку, обязательно
`dry_run`	bool	`false`	проверить правки и показать результат без записи

`action`	Поля	Что делает
`append`	`item` или `items`: `{locale, slug?, name?, rtl?, flag?, order?}`	добавляет язык; по `locale` из `site.locales` остальное подставляется из каталога. Тот же язык ещё раз — `changed: false`
`merge`	`match: {"slug": …}` или `{"locale": …}`, `fields: {name?, slug?, locale?, rtl?, flag?, order?}`	меняет язык; новый `slug` меняет адреса всех страниц языка
`set_default`	`match: {"slug": …}`	делает язык основным
`remove`	`match: {"slug": …}`, `confirm` — тот же слаг	удаляет язык; его страницы перестают открываться

operations — итог каждой правки: index, action, slug, changed, у merge — fields, у remove — usage. languages — все языки после правки в полной форме: ещё term_id, w3c, flag_url, front_page: {id, url}, counts: {posts, terms}; settings — настройки адресов, как у PATCH /languages. Фреймы, которые печатают языки, пересобираются фоном за минуту-две (rebaked.status: "started"). С dry_run ответ — dry_run: true, applied: false, operations и languages такими, какими они станут.

Удаление. Без confirm, равного слагу, удаление отвечает 428 confirmation_required с confirm_with и usage: {pages, posts, terms}. Посмотреть, что удалится, не удаляя, — "dry_run": true: у каждого удаления в operations будут usage и confirm_with. Например, удалить немецкий с подтверждением:

curl -s -X PATCH "$API/site/$SITE/data/site.languages" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"patch": [{"action": "remove", "match": {"slug": "de"}, "confirm": "de"}]}'

{ "success": true, "site_id": "x9HTLHECq", "applied": true, "operations": [ { "index": 0, "action": "remove", "slug": "de", "changed": true, "usage": { "posts": 0, "pages": 0, "terms": 0 } } ], "default": "en", "languages": [ "…" ] }

Всё или ничего. Сначала вся правка проверяется по текущим языкам, и любая ошибка не меняет ничего; в отказе — index и action правки, на которой остановились. Потом правки применяются по порядку, удаления — последними. Если правка не прошла посреди пачки, уже сделанные откатываются: добавленный язык удаляется, изменённый получает прежние поля, основной возвращается; в отказе — rolled_back. Удалённый язык вернуть нельзя, поэтому удаления идут в конце.

Код	Статус	Когда	Что делать
`nothing_to_update`	400	нет `patch`	пришлите список правок
`bad_patch_op`	400	неизвестное `action` или у правки нет нужного поля, например `fields` у `merge`	исправьте правку по `message`
`item_ref_required`	400	у правки нет `match`	добавьте `{"match": {"slug": …}}`
`computed_source`	409	запись в `site.locales`	каталог только читается; язык добавляет `append`
`whole_list_not_accepted`	400	прислан список `items` целиком	присылайте правки `patch`
`locale_required`, `invalid_locale`	400	у `append` нет `locale` или он неверный	возьмите `locale` из `site.locales`
`locale_unknown`	400	локали нет в `site.locales`	передайте `slug` и `name` сами
`invalid_language`, `invalid_name`, `invalid_flag`, `invalid_order`	400	значение поля неверной формы	исправьте поле
`unknown_field`	400	поле вне списка	уберите поле
`nothing_to_change`	400	в `fields` нет ни одного поля языка	пришлите хотя бы одно поле
`conflicting_edits`	400	один слаг и добавлен, и удалён в одной правке	разнесите правки
`pll_invalid_slug`, `pll_non_unique_slug`, `pll_invalid_locale`, `pll_invalid_flag`, `pll_invalid_name`	400	сайт отклонил значение	исправьте значение из `message`
`language_not_found`	404	языка с таким слагом нет	возьмите слаг из `GET /data/site.languages`
`language_exists`	409	слаг уже занят другим языком; разница в `diff`	выберите другой `slug`
`language_is_default`	409	удаляется основной язык	сначала `set_default` другого языка — можно в той же правке
`last_language`	409	удаляется последний язык	—
`confirmation_required`	428	`remove` без `confirm`	повторите с `"confirm": "<слаг>"`

PATCH /languages

Меняет настройки адресов языков — как языки видны в адресе сайта. Применяются начиная с force_lang. Например, убрать префикс основного языка и включить переадресацию:

curl -s -X PATCH "$API/site/$SITE/languages" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"hide_default": true, "redirect_lang": true}'

Поле	Тип	По умолчанию	Описание
`force_lang`	int	—	где язык в адресе: `1` — каталог `/ru/`, `2` — поддомен, `3` — свой домен
`hide_default`	bool	—	основной язык без префикса; при `force_lang: 3` выключается
`redirect_lang`	bool	—	главная языка открывается по адресу с кодом языка (`/ru/`), а не по своему слагу
`rewrite`	bool	—	убирать служебный префикс `/language/` из адресов
`browser`	bool	—	выбирать язык по браузеру при первом заходе
`media_support`	bool	—	переводить медиафайлы

Ответ: changed — записанные ключи, before — значения до записи, settings — перечитанные после, default и languages. Настройки адресов пока не переехали в данные: адрес /data у них появится позже (скоро).

Код	Статус	Когда	Что делать
`nothing_to_change`	400	в теле нет ни одного поля	пришлите хотя бы одно поле
`unknown_field`	400	поле вне списка; допустимые — в `message`	уберите поле
`invalid_force_lang`	400	`force_lang` не 1, 2 или 3	исправьте значение