Языки сайта

Языки — это Polylang. Язык сайта задаёт, какие языковые версии страниц, меню и наборов данных вообще возможны и как язык попадает в адрес. Язык отдельной страницы и переводы описаны на странице языки и переводы страниц.

Все ручки — под $API/site/$SITE/languages. Сайт без Polylang отвечает на любую из них 409 polylang_inactive.

Что есть на сайте

curl -s -H "Authorization: Bearer $OP_TOKEN" "$API/site/$SITE/languages" | jq '{default, settings, languages: [.languages[] | {slug, locale, name, is_default, url, front_page, counts}]}'

{
  "default": "en",
  "settings": { "force_lang": 1, "hide_default": true, "redirect_lang": true, "rewrite": true, "browser": false, "media_support": true },
  "languages": [
    { "slug": "en", "locale": "en_US", "name": "English", "is_default": true, "url": "https://test.onpress.pro/", "front_page": { "id": 5776, "url": "https://test.onpress.pro/" }, "counts": { "posts": 41, "terms": 8 } },
    { "slug": "ru", "locale": "ru_RU", "name": "Русский", "is_default": false, "url": "https://test.onpress.pro/ru/", "front_page": { "id": 6037, "url": "https://test.onpress.pro/ru/" }, "counts": { "posts": 37, "terms": 1 } }
  ]
}

Поле языка	Смысл
`slug`	код языка в адресах и в `lang` всего API
`locale`	локаль WordPress: `en_US`, `ru_RU`, `zh_CN`
`name`	отображаемое имя
`rtl`	письмо справа налево
`order`	место в переключателе
`flag`, `flag_url`	код флага и адрес картинки
`is_default`	язык по умолчанию
`term_id`	терм языка
`w3c`	код для `hreflang`
`url`	адрес главной языка
`front_page`	`{id, url}` главной страницы языка или `null` — тогда по `/{slug}/` открывается архив
`counts`	сколько записей и терминов в этом языке

Один язык — GET $API/site/$SITE/languages/ru (ответ {language: {…}}). Нет такого — 404 language_not_found, строка не похожа на слаг — 400 invalid_language.

Все остальные ручки языков отвечают полным состоянием: default, settings и languages целиком, плюс поле cache — какие кэши сброшены после записи. Неудачный сброс кэша не превращает успешную запись в ошибку.

Добавить язык

curl -s -X POST "$API/site/$SITE/languages" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"locale": "de_DE"}' | jq '{changed, language, default}'

Обязательна только locale — имя, слаг, направление письма и флаг Polylang берёт из своего списка. Остальное можно задать явно:

Поле	Правило
`locale`	обязательно; вид `ab`, `ab_CD`, `ab_CD_x`; иначе `400 invalid_locale`. Локаль, которой Polylang не знает, требует явных `slug` и `name` (`400 locale_unknown`)
`slug`	`^[a-z][a-z0-9_-]*$`
`name`	не пустое
`rtl`	направление письма
`flag`	код флага, 2–16 символов `[a-z0-9_-]`
`order`	место в переключателе, целое
`default_category`	создать рубрику «Без рубрики» для языка; по умолчанию нет — у сайтов v2 рубрик нет

Добавление идемпотентно: язык создан — 201, язык уже был ровно таким — 200 и changed: false. Тот же слаг с другими свойствами — 409 language_exists с diff ({поле: {is, want}}, сравниваются только присланные поля). Менять существующий язык — PATCH, а не повторным POST.

У нового языка нет ни главной (front_page: null), ни страниц, ни меню. Что сделать дальше — рецепт многоязычного сайта.

Изменить язык

curl -s -X PATCH "$API/site/$SITE/languages/de" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"name": "Deutsch", "order": 3}' | jq '{changed, diff}'

Поля: slug, locale, name, rtl, flag, order — с теми же проверками. Пустое тело — 400 nothing_to_change; ничего не изменилось — changed: false. Смена слага меняет адрес каждой страницы языка — делайте это до того, как у сайта появится трафик. Отказы Polylang приходят своими кодами с подробностями в details: pll_invalid_slug, pll_non_unique_slug, pll_invalid_locale, pll_invalid_flag, pll_invalid_name (все 400).

Язык по умолчанию

curl -s -X PUT "$API/site/$SITE/languages/default" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"lang": "ru"}' | jq '{changed, was, default}'

Это не косметика: при hide_default язык по умолчанию живёт в адресах без префикса, а главная сайта всегда хранит страницу языка по умолчанию. Правила адресов пересобираются в том же вызове. Уже основной — changed: false.

Удалить язык

curl -s -X DELETE "$API/site/$SITE/languages/de" -H "Authorization: Bearer $OP_TOKEN" | jq '{deleted, usage}'

Polylang удаляет терм языка, а не контент: страницы языка остаются в базе без языка и перестают открываться. Поэтому ручка отказывает:

409 language_in_use — у языка есть записи или термины (счёт в usage: {posts, pages, terms}). Удалите содержимое или передайте force=1 (в строке запроса или теле), принимая последствия;
409 language_is_default — язык по умолчанию: сначала назначьте другой;
409 last_language — единственный язык сайта.

force снимает только первый отказ. usage в ответе — счёт до удаления.

Как язык попадает в адрес

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}' | jq '{changed, before, settings}'

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

Эти настройки меняют адрес каждой страницы сайта, поэтому живут отдельно от настроек сайта и проверяются вместе: force_lang применяется первым. changed — список реально записанных ключей, before — как было, settings в ответе перечитан после записи — там видно значение, которое Polylang поправил сам. Хотя бы одно поле обязательно (400 nothing_to_change), чужое — 400 unknown_field, force_lang вне 1–3 — 400 invalid_force_lang.

Типичная настройка сайтов сети: force_lang: 1, hide_default: true, redirect_lang: true, rewrite: true.

Языки как данные

Список языков доступен фреймам как системный источник site.languages (повторитель) и вставкой onpress/lang-switcher. Через источник можно поменять язык: PATCH /data/site.languages {"lang": "ru", "name": "Русский"} или {"default": "ru"}. Добавлять и удалять языки — только ручками выше.

Если адреса языков странные

Список языков Polylang кэширует. Если url в ответе указывает не на тот домен (например после смены домена сайта), сбросьте кэш языков:

curl -s -X POST "$API/site/$SITE/cache/flush" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"polylang": true}' | jq .flushed