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

Обратная связь по переводам редко приходит через клик в дашборде. Чаще это строка в инструменте поддержки, заметка от рецензента или задача в QA-очереди: «не переводите название продукта», «используйте формальный регистр в немецком». API Engine 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

Возвращает предложения движка, полученные при любом запуске генерации: на основе текста, через …/suggestions/generate или автоматически по низким оценкам в ответах пользовательских измерений. Каждая запись — предлагаемая правка с обоснованием.

[
  {
    "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 rule 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 rule 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 образуют единый цикл, которым можно полностью управлять из кода: передать обратную связь, посмотреть, что было предложено, и применить те правки, с которыми вы согласны.

Что дальше#