Войти
Устройство сайта
Markdown
Открыть в ИИ

Языки и переводы

Любой сайт на платформе может работать на нескольких языках. У каждой языковой версии свой адрес, например /en/, своя главная страница, свои страницы, меню и данные. Вы добавляете языки, выбираете основной и удаляете лишние через API.

Чтобы перевести сайт, достаточно добавить язык и записать страницы, меню и данные с lang этого языка: вёрстка у всех языков общая.

Прочитать

GET /data/site.languages отдаёт языки сайта: код slug, название, локаль, адрес главной языка, признак основного языка is_default и число материалов на языке. Например:

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

Какие языки можно добавить

GET /data/site.locales отдаёт все языки, которые можно добавить: локаль locale, код slug, название, флаг и признак added — язык уже есть на сайте. Например:

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

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

Передайте в PATCH /data/site.languages правку append с локалью из списка выше: название, код, флаг и направление письма подставятся сами. У нового языка ещё нет главной, страниц и меню — их создают переводом, как описано ниже. Например, немецкий:

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

Изменить

Правка merge в PATCH /data/site.languages меняет поля одного языка: name, slug, locale, flag, rtl или order — место в переключателе языков. Новый slug меняет адрес каждой страницы языка. Например, переименовать немецкий и поставить его третьим:

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

Основной язык

Главная сайта — страница основного языка, и основной язык открывается без кода в адресе. Чтобы сменить основной язык, передайте правку set_default в PATCH /data/site.languages. Например, сделать основным английский:

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

Удалить язык

Вместе с языком удаляются его страницы, поэтому удаление нужно подтвердить: передайте правку remove в PATCH /data/site.languages и код языка в confirm. Например, удалить немецкий:

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

Перевести страницу

Перевод — отдельная страница на нужном языке, связанная с оригиналом. Выгрузите оригинал с ?as=translation_source: в ответе уже стоит translation_of со ссылкой на оригинал. Переведите текст, замените lang на язык перевода и опубликуйте через POST /pages/markdown. Например, английская версия страницы 6183:

curl -s "$API/site/$SITE/pages/6183/markdown?as=translation_source" -H "Authorization: Bearer $OP_TOKEN"

curl -s -X POST "$API/site/$SITE/pages/markdown" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d @page.en.json

Как перевести страницу целиком вместе с меню и данными — в кейсе Перевод страницы.

Переключатель языков

Переключатель языков выводит системный фрейм lang-switcher. Он показывает языки, на которых опубликована текущая страница, и ведет на ее переводы. Новый перевод появляется в нем сам. Например, выпадающий список:

<!-- frame/lang-switcher--dropdown /-->

Простой список выводит фрейм lang-switcher. Параметр hide_current убирает текущий язык, label задает подпись выпадающего списка. Верстку переключателя можно менять. Внутри фрейма стоит повторитель по системным данным pages.translations: у каждого языка есть name, code (EN), url и признак current. Чтобы показывать коды вместо названий, замените в разметке item.name на item.code. Если фрейма на сайте нет, поставьте его через POST /site/{site_id}/frames/system/lang-switcher/install и правьте через PUT /frames/lang-switcher. Страница на одном языке переключатель не выводит.

Вопросы и ответы

Можно ли записать весь список языков одним запросом?

Нет, API ответит 400 whole_list_not_accepted: лишний или пропавший язык в списке означал бы добавить или удалить язык вместе с материалами. Меняйте по одному языку.

Почему язык не удаляется?

На языке есть материалы — 409 language_in_use, это основной язык — 409 language_is_default или единственный — 409 last_language. Основной язык сначала смените на другой.

Как вынести язык на поддомен или отдельный домен?

Это настройки адресов языков, их меняет PATCH /languages, см. справочник API. Они меняют адрес каждой страницы, поэтому настраивайте их до запуска сайта.

Где коды ошибок?

В справочнике API. Ответ с ошибкой сам называет причину и нужный эндпоинт.