Войти
Кейсы
Markdown
Открыть в ИИ

Перевод страницы

Перевод страницы — отдельная страница на другом языке, связанная с оригиналом. Связь даёт посетителю переход между версиями в переключателе языков, а поисковикам — ссылки hreflang. Весь перевод — пять запросов к API: проверить язык, выгрузить оригинал, опубликовать перевод, записать меню и данные на новом языке.

Ваш агент получает страницу одним Markdown-документом: текст, SEO-поля и ссылка на оригинал лежат в нём рядом. Агенту остаётся перевести текст и поменять язык и адрес, вёрстку он не трогает.

Проверить язык

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

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

Выгрузить оригинал

GET /pages/{ref}/markdown?as=translation_source отдаёт страницу Markdown-документом, подготовленным под перевод: вместо id в свойствах стоит translation_of с id оригинала, а status убран, чтобы вы задали его сами. Например, выгрузите страницу 6183:

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

Документ приходит в поле markdown:

---
translation_of: 6183
name: "О компании"
seo_title: "О компании: кто мы и как работаем"
seo_description: "Команда, история и принципы работы."
slug: "o-kompanii"
url: "/o-kompanii/"
lang: "ru"
frame: "article"
---

# О компании

Мы делаем сайты для малого бизнеса с 2015 года.

Перевести

Переведите текст и SEO-поля в свойствах: name, seo_title, seo_description и excerpt, если он есть. Замените lang на язык перевода, slug — на слаг на этом языке, а url — на адрес с префиксом языка. Добавьте status: publish откроет перевод сразу, draft сохранит черновиком. translation_of и frame оставьте как есть, ссылки на другие страницы сайта замените адресами их переводов. Например, свойства английской версии:

---
translation_of: 6183
name: "About us"
seo_title: "About us: who we are and how we work"
seo_description: "Our team, history and principles."
slug: "about"
url: "/en/about/"
lang: "en"
status: "publish"
frame: "article"
---

# About us

We have been building websites for small businesses since 2015.

Опубликовать

POST /pages/markdown создаёт страницу и в том же запросе связывает её с оригиналом по translation_of: либо страница сохранена и связана, либо не записано ничего. Например, опубликуйте перевод из файла about.en.json, где в поле markdown лежит документ из прошлого шага:

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

Ответ показывает связь: translations — вся группа переводов в виде {язык: id}, translation_group — оригинал и что изменилось.

{
  "success": true,
  "id": 6390,
  "lang": "en",
  "link": "https://example.com/en/about/",
  "translations": { "en": 6390, "ru": 6183 },
  "translation_group": { "origin": { "id": 6183, "lang": "ru" }, "created": true, "changed": true, "unlinked": [] }
}

Следующий язык публикуйте с тем же translation_of: группа пополнится, а не заменится. Чтобы позже поправить перевод, выгрузите сам перевод без as — в свойствах будет его id — и опубликуйте снова.

Перевести данные

Часть текстов страница выводит не из своего Markdown, а из данных: меню шапки, отзывы, карточки. У каждого языка своё меню и свой вариант пользовательского набора, поэтому запишите их на языке перевода отдельно. Какие наборы читает страница, показывает поле datasets в ответе GET /pages/{ref}/export.

Пользовательские наборы

PUT /data/{имя} с lang записывает вариант набора на этом языке рядом с общим списком, остальные языки по-прежнему читают общий. Поля элементов и их порядок оставьте как в оригинале, переводите только значения. Например, английские отзывы:

curl -s -X PUT "$API/site/$SITE/data/reviews" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"lang": "en", "items": [
        {"name": "Anna", "text": "The site was live in a day."}
      ]}'

PUT /data/menu.header с lang заменяет меню шапки этого языка. Прочитайте меню оригинала с ?lang=ru, переведите подписи, а пункты на страницы направьте на переводы — адресом с префиксом языка. Если у языка ещё нет своего меню, запись ответит 404 menu_not_assigned: создайте его, как в разделе Создать меню. Например, английское меню шапки с новой страницей:

curl -s -X PUT "$API/site/$SITE/data/menu.header" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"lang": "en", "items": [
        {"page": "/en/docs/", "title": "Docs"},
        {"page": "/en/about/", "title": "About us"}
      ]}'

Проверить результат

Откройте адрес перевода: страница отвечает 200, в <html> стоит язык перевода, а в <head> — ссылки hreflang на обе версии и x-default на версию основного языка. Например:

curl -s "https://example.com/en/about/"

В ответе:

<html lang="en-US">
<link rel="alternate" href="https://example.com/o-kompanii/" hreflang="ru" />
<link rel="alternate" href="https://example.com/en/about/" hreflang="en" />
<link rel="alternate" href="https://example.com/o-kompanii/" hreflang="x-default" />

В переключателе языков на обеих страницах пункт другого языка ведёт на парную страницу, а не на главную этого языка, и в шапке английской версии стоит английское меню. Нет hreflang — страница не связана с оригиналом: группу показывает GET /pages/{ref}/translations.

Всё одним запросом

GET /pages/{ref}/export отдаёт одним JSON страницу под перевод вместе с данными, которые она выводит, а POST /pages/import записывает переведённую выгрузку обратно: страницу с translation_of, варианты наборов и меню на языке перевода. Импорт сначала проверяет все части и при ошибке не записывает ничего. Например, выгрузите страницу 6183, переведите файл и отправьте его обратно:

curl -s "$API/site/$SITE/pages/6183/export" -H "Authorization: Bearer $OP_TOKEN"

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

Частые ошибки

422 translation_link_failed, reason: same_language. В lang остался язык оригинала. Замените lang на язык перевода и опубликуйте снова: страница не создана.

409 lang_mismatch. В свойствах стоит id оригинала, а lang — другой: такой запрос перезаписал бы оригинал. Замените id на translation_of с тем же значением или выгрузите оригинал заново с ?as=translation_source.

409 translation_group_conflict. Страница с таким slug на языке перевода уже есть и связана с другой страницей. Выведите её из той группы через DELETE /pages/{ref}/translations и опубликуйте перевод снова или возьмите другой slug.

Остальные коды — в справочнике API. Ответ с ошибкой сам называет причину.