API предложений движка

Создавайте предложения на основе обратной связи, изучайте изменения и принимайте решение — применить их или отклонить.

Предложения движка — это изменения терминов глоссария, правил и вариантов тональности бренда. Перед применением проверьте, что предлагается изменить и куда будут внесены изменения. Генерация добавляет предложения в очередь, а применение меняет инструкции движка.

Предложения движка доступны в рамках плана Enterprise. Для вызова API также нужен доступ к движку и соответствующие разрешения для работы с предложениями. О рабочем процессе в панели управления см. Предложения в Очереди.

Все указанные ниже маршруты используют https://api.lingo.dev и аутентификацию API.

Запросить генерацию #

Чтобы создать предложения на основе обратной связи, собранной движком:

http
POST /v2/engines/:engineId/engine-suggestions/generate
X-API-Key: YOUR_API_KEY

У этого запроса нет тела. Чтобы передать обратную связь напрямую:

http
POST /v2/engines/:engineId/engine-suggestions/from-text
Content-Type: application/json
X-API-Key: YOUR_API_KEY
json
{
  "text": "In German account settings, use Abonnement for subscription. Avoid Mitgliedschaft for this product feature."
}

В text должен быть текст длиной не более 10 000 символов, состоящий не только из пробельных символов. В этом режиме предложения создаются на основе самой переданной обратной связи, поэтому укажите нужное исправление и язык, к которому оно относится.

Оба маршрута возвращают HTTP 200 со следующим содержимым:

json
{ "enqueued": true }

Это подтверждает отправку в очередь, а не завершение генерации. После обработки запросите список предложений движка, ожидающих решения. Если полезных изменений нет, генерация может не создать ни одного предложения. Пустой список сразу после запроса не означает, что запрос завершился с ошибкой.

Получить список предложений #

http
GET /v2/organizations/:orgId/engine-suggestions?engineIds=YOUR_ENGINE_ID&statuses=Pending&limit=25
Параметр запросаОписание
engineIdsОграничивает результаты выбранными движками.
targetLocalesЛокали, на которые распространяются инструкции, включая * для инструкций, общих для всех локалей.
statusesPending, Applied или Dismissed. По умолчанию — Pending.
idsВозвращает предложения с выбранными ИД.
limitЦелое число от 1 до 100. По умолчанию — 25.
cursorНепрозрачный курсор пагинации.

Чтобы передать несколько значений, повторите параметры-массивы. Ответ содержит data и meta.nextCursor. Продолжайте запрашивать данные с теми же фильтрами, пока nextCursor не примет значение null.

Каждое предложение содержит:

ПолеОписание
id, organizationId, engineIdИдентификатор предложения и сведения о том, кому оно принадлежит.
targetLocaleЛокали, на которые распространяется предлагаемое изменение.
changeИзменение с указанием типа, описанное ниже.
reasoningОбоснование предложения.
sourcesСсылки на подтверждающие данные, например на оценку модели-оценщика, ручную правку или рабочую задачу.
statusОбъект, в котором type имеет значение Pending, Applied или Dismissed.
destinationНабор инструкций, в который вносится изменение, или null, если набор недоступен.
createdAt, updatedAtМетки времени в формате ISO.

Место назначения содержит kind (Glossary, Ruleset или BrandVoice), id с допустимым значением null, name и willCreate. Проверьте willCreate, чтобы узнать, будет ли при применении создан набор инструкций. Статус применения содержит at, а также by и target, которые могут иметь значение null. Предложения, отклонённые системой, могут содержать reason.

Изучить изменение #

change.typeСодержимое
AddGlossaryTermsourceLocale, sourceText, targetLocale, targetText, description с допустимым значением null и nonTranslatable.
UpdateGlossaryTermtermId, glossaryId с допустимым значением null и переданные поля для замены.
AddRulename, text и targetLocale.
UpdateRuleruleId и переданные name, text или targetLocale.
AddBrandVoiceVariationtargetLocale и text.
UpdateBrandVoiceVariationvariationId и переданные targetLocale или text.

Предложения по обновлению содержат только поля, которые меняются. Перед применением масштабного изменения проверьте целевую запись и то, где ещё используется её набор инструкций.

Применить или отклонить #

http
POST /v2/engine-suggestions/:id/apply
http
POST /v2/engine-suggestions/:id/dismiss

У обоих запросов нет тела. Они возвращают обновлённое предложение. Принять решение можно только по предложениям, которые ещё его ожидают. При применении записываются предложенные инструкции, а при отклонении инструкции остаются без изменений.

Если целевой объект изменился или исчез, запрос на применение может вернуть EngineSuggestionConflicts или EngineSuggestionTargetGone. Прежде чем выбирать исправление, обновите данные предложения и целевого объекта. Если решение по предложению уже принято, повторный запрос вернёт EngineSuggestionNotPending. Если ответ неоднозначен, проверьте состояние предложения вместо того, чтобы вслепую повторять запись.

Принять решение по нескольким предложениям #

Отправьте { "ids": ["FIRST_ID", "SECOND_ID"] } методом POST по адресам:

  • /v2/engine-suggestions/apply-many: 1–25 уникальных ИД.
  • /v2/engine-suggestions/dismiss-many: 1–1 000 уникальных ИД.

Запрос на применение возвращает applied и failed, а запрос на отклонение — dismissed и failed. Каждая запись с ошибкой содержит id и именованную ошибку error. Успешный HTTP-ответ может содержать ошибки для отдельных элементов. Успешные результаты сохраняются, даже если обработка другого элемента завершилась с ошибкой, поэтому обрабатывайте каждый результат отдельно.

Использовать обновлённые инструкции #

После применения проверьте глоссарий, правила или тональность бренда движка и протестируйте их на типичном контенте. Примените одобренные инструкции перед запуском нового задания. Чтобы обновить существующие переводы, отдельно выберите нужный контент и запросите обновление. Само по себе применение инструкций не запускает повторный перевод.