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

Обратная связь по переводам редко приходит в виде клика в панели. Обычно это строка в вашей системе поддержки, заметка от проверяющего, запись в очереди QA — «не переводите название продукта», «используйте формальный стиль в немецком». API предложений для движка превращает такой произвольный текст в изменения движка через код: вы отправляете обратную связь текстом, платформа анализирует её и возвращает конкретные структурированные правки для глоссария, инструкций или тональности бренда движка, которые вы затем можете применить.

Это программный аналог функции в панели управления. Там предложения генерируются автоматически, когда ваши AI-оценщики ставят переводу низкую оценку; здесь вы сами передаёте сигнал в виде текста. В обоих случаях результат один и тот же — ожидающие предложения, которые вы проверяете и применяете.

Процесс состоит из двух частей. Генерация выполняется асинхронно: вы передаёте обратную связь, а платформа в фоновом режиме анализирует её и добавляет в движок ожидающие предложения. Проверка выполняется синхронно: вы получаете список ожидающих предложений, читаете, что именно предлагается, и применяете или отклоняете каждое из них. На этой странице описаны обе части. О сценарии в панели управления — автоматической генерации на основе низких оценок проверки, вкладке Suggestions и уведомлениях — см. Предложения для движка.

Генерация из обратной связи#

POST /engines/:id/suggestions/from-text

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

const response = await fetch(
  `https://api.lingo.dev/engines/${engineId}/suggestions/from-text`,
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.LINGO_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      text: "Our German (de-DE) translations keep using the informal 'du'. For our B2B audience they must always use the formal 'Sie'.",
    }),
  },
);

const { enqueued } = await response.json();
console.log(enqueued); // true – generation accepted, running in the background

{ "enqueued": true }

enqueued: true означает, что платформа приняла задачу в работу, а не что предложения уже готовы. Генерация — это один фоновый этап: платформа читает ваш текст, анализирует конфигурацию, убирает дубликаты относительно того, что уже есть, и сохраняет всё, что предлагает. Вполне нормально, если по итогам запуска не будет предложено ничего вовсе (например, если обратная связь была слишком расплывчатой или движок уже это учитывает). Чтобы увидеть результат, через несколько секунд получите список предложений движка.

Список ожидающих предложений#

GET /engines/:id/suggestions

Возвращает предложения движка — результат любого запуска генерации, будь то по тексту, по нажатию кнопки вручную или автоматически на основе низких оценок проверки. Каждая запись — это предложенная правка с пояснением.

[
  {
    "id": "egs_A1b2C3d4E5f6G7h8",
    "ownerOrganizationId": "org_X1y2Z3a4B5c6D7e8",
    "ownerEngineId": "eng_X1y2Z3a4B5c6D7e8",
    "actionType": "add_instruction",
    "targetKind": "instruction",
    "targetId": null,
    "targetLocale": "de-DE",
    "payload": { "instruction": "Use the formal 'Sie' form in all German translations; never use the informal 'du'." },
    "reasoning": "Feedback states the B2B audience requires formal address, but the engine has no instruction enforcing it.",
    "sourceReviewLogIds": [],
    "status": "pending",
    "appliedTargetId": null,
    "createdAt": "2026-06-18T10:30:00.000Z"
  }
]

Именно payload делает применение простым: предлагаемое изменение полностью структурируется ещё на этапе генерации, поэтому применение — это обычная запись, а не ещё один раунд работы AI. Решение принимаете вы; платформа ничего не переанализирует.

Применение предложения#

POST /engine-suggestions/:id/apply

Записывает предложенное изменение в движок и помечает предложение как applied. Это детерминированная запись payload, которую вы уже видели в списке — второго вызова AI нет, поэтому записывается ровно то, что вы проверили. Предложение типа add_* создаёт новый элемент глоссария, инструкцию или тональность бренда; предложение типа update_* изменяет существующую запись, указанную в targetId.

const response = await fetch(
  `https://api.lingo.dev/engine-suggestions/${suggestionId}/apply`,
  {
    method: "POST",
    headers: { "X-API-Key": process.env.LINGO_API_KEY },
  },
);

const applied = await response.json();
console.log(applied.status);          // "applied"
console.log(applied.appliedTargetId); // "ins_…" – the instruction it just created

В ответе возвращается предложение в состоянии applied, где appliedTargetId теперь указывает на реальную запись движка, которая была создана или обновлена. С этого момента это обычный элемент глоссария, инструкция или настройка тональности бренда — её можно открыть, изменить или удалить, как и любую другую.

Отклонение предложения#

POST /engine-suggestions/:id/dismiss

Удаляет ненужное предложение, помечая его как dismissed и не меняя движок. Используйте это, если предложение не подходит вашему продукту: движок останется без изменений, а предложение перестанет отображаться как ожидающее.

await fetch(
  `https://api.lingo.dev/engine-suggestions/${suggestionId}/dismiss`,
  {
    method: "POST",
    headers: { "X-API-Key": process.env.LINGO_API_KEY },
  },
);
// The suggestion is now "dismissed"; nothing was written to the engine.

Полный цикл#

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

Что дальше#