API de sugerencias del motor

Los comentarios sobre tus traducciones rara vez llegan con un clic en un panel de control. Suelen aparecer como una línea en tu propia herramienta de soporte, una nota de una persona revisora o una fila en tu propia cola de QA: "deja de traducir el nombre del producto", "usa el registro formal en alemán". La API de sugerencias del motor convierte ese texto libre en cambios en el motor desde el código: envía los comentarios como texto, la plataforma los interpreta y te devuelve cambios concretos y estructurados para el glosario, las reglas o la voz de marca de tu motor, listos para aplicar.

Esta función permite hacer mediante código lo mismo que desde el panel. Allí, las sugerencias se generan automáticamente cuando una de tus mediciones personalizadas devuelve una puntuación baja para una traducción; aquí, tú aportas la señal en forma de texto. En ambos casos, el resultado es el mismo: sugerencias pendientes que puedes revisar y aplicar.

El flujo tiene dos partes. La Generación es asíncrona: envías tus comentarios y la plataforma los analiza en segundo plano para crear sugerencias pendientes en el motor. La Revisión es síncrona: consultas la lista de sugerencias pendientes, lees lo que propone cada una y las aplicas o descartas. Esta página explica ambas partes. Para conocer cómo funciona en el panel —la generación automática a partir de respuestas con puntuaciones bajas de las mediciones personalizadas, el interruptor Proponer mejoras en la pestaña Evaluadores del motor y La Cola, donde las sugerencias quedan pendientes de una decisión—, consulta Sugerencias del motor.

Generar a partir de feedback#

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

Envía una descripción en texto plano de lo que el motor está haciendo mal. La plataforma razona sobre ese texto junto con la configuración actual del motor y propone ediciones atómicas; no volverá a proponer algo que el motor ya tenga. La generación se ejecuta de forma asíncrona, así que la llamada devuelve en cuanto se acepta el trabajo, no cuando las sugerencias ya están listas.

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 significa que la plataforma ha aceptado el trabajo, no que ya existan sugerencias. La generación es un paso en segundo plano: lee tu texto, razona sobre la configuración, elimina duplicados respecto a lo que ya existe y guarda todo lo que proponga. Es perfectamente posible que una ejecución no proponga nada (porque el feedback era impreciso o porque el motor ya lo cubre). Consulta los resultados enumerando las sugerencias del motor unos instantes después.

Enumerar las sugerencias pendientes#

GET /engines/:id/suggestions

Devuelve las sugerencias del motor: el resultado de cualquier ejecución de generación, ya sea a partir de texto, de …/suggestions/generate o de forma automática a partir de respuestas con puntuaciones bajas de las mediciones personalizadas. Cada entrada contiene una propuesta de cambio y el razonamiento que la justifica.

[
  {
    "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"
  }
]

El payload es el detalle que hace que aplicar sea tan sencillo: el cambio propuesto queda totalmente estructurado en el momento de la generación, así que aplicarlo es una simple escritura, no otra ronda de IA. Tú decides; la plataforma no vuelve a razonar.

Aplicar una sugerencia#

POST /engine-suggestions/:id/apply

Escribe el cambio propuesto en el motor y marca la sugerencia como applied. Es una escritura determinista del payload que ya viste en la lista: no hay una segunda llamada a la IA, así que lo que revisaste es exactamente lo que se escribe. Una sugerencia add_* crea un nuevo elemento de glosario, una regla o una voz de marca; una sugerencia update_* modifica la entrada existente identificada por 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

La respuesta es la sugerencia en su estado applied, con appliedTargetId apuntando ahora a la entrada real del motor que ha creado o actualizado. A partir de ese momento, esa entrada pasa a ser un elemento normal del glosario, una regla o una voz de marca: ábrela, edítala o elimínala como cualquier otra.

Descartar una sugerencia#

POST /engine-suggestions/:id/dismiss

Descarta una sugerencia que no quieres, la marca como dismissed y deja el motor intacto. Úsalo cuando una propuesta no encaje con tu producto: el motor no cambia y la sugerencia deja de mostrarse como pendiente.

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.

El ciclo completo, de principio a fin#

Los cuatro endpoints forman un ciclo que puedes controlar íntegramente desde código: envía feedback, revisa lo que se ha propuesto y confirma las ediciones con las que estés de acuerdo.

Siguientes pasos#