API de sugerencias del motor

Genera propuestas a partir de comentarios, revisa sus cambios y aplícalas o descártalas de forma explícita.

Las sugerencias del motor proponen cambios en los términos del glosario, las reglas y las variaciones de la voz de marca. Revisa el contenido propuesto y su destino antes de aplicarlo. La generación agrega propuestas a La Cola; aplicar una propuesta modifica las directrices del motor.

Las sugerencias del motor están disponibles en el plan Enterprise. Quien realiza la llamada también necesita acceso al motor y los permisos correspondientes para las sugerencias. Consulta Sugerencias en La Cola para conocer el flujo de trabajo en el panel.

Todas las rutas siguientes usan https://api.lingo.dev y autenticación de API.

Solicitar generación #

Genera propuestas a partir de los comentarios recopilados por el motor:

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

Esta solicitud no tiene cuerpo. Para proporcionar comentarios directamente:

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 debe incluir contenido que no sea solo espacios en blanco y no superar los 10,000 caracteres. Este modo genera propuestas a partir de los comentarios proporcionados, así que incluye la corrección deseada y el idioma al que se aplica.

Ambas rutas devuelven HTTP 200 con:

json
{ "enqueued": true }

Esto confirma el envío a La Cola, no que la generación haya terminado. Consulta la lista de sugerencias pendientes del motor después del procesamiento. La generación puede no producir propuestas si no hay ningún cambio útil que hacer; recibir una lista vacía de inmediato no significa que la solicitud haya fallado.

Listar propuestas #

http
GET /v2/organizations/:orgId/engine-suggestions?engineIds=YOUR_ENGINE_ID&statuses=Pending&limit=25
Parámetro de consultaSignificado
engineIdsLimita los resultados a los motores seleccionados.
targetLocalesÁmbitos de idioma, incluido * para las directrices que se aplican a todos los idiomas.
statusesPending, Applied o Dismissed; el valor predeterminado es Pending.
idsObtiene los ID de propuesta seleccionados.
limitNúmero entero de 1 a 100; el valor predeterminado es 25.
cursorCursor de paginación opaco.

Repite los parámetros de arreglo para incluir varios valores. La respuesta contiene data y meta.nextCursor; continúa con los mismos filtros hasta que nextCursor sea null.

Cada propuesta incluye:

CampoSignificado
id, organizationId, engineIdIdentidad y titularidad de la propuesta.
targetLocaleÁmbito de idioma del cambio propuesto.
changeCambio con un tipo definido, descrito a continuación.
reasoningExplicación de la propuesta.
sourcesReferencias de evidencia, como una revisión de un sistema de puntuación, una edición humana o un elemento de trabajo.
statusObjeto cuyo type es Pending, Applied o Dismissed.
destinationConjunto de directrices que recibe el cambio, o null si no está disponible.
createdAt, updatedAtMarcas de tiempo ISO.

Un destino incluye kind (Glossary, Ruleset o BrandVoice), id que admite valores nulos, name y willCreate. Consulta willCreate para saber si al aplicar la propuesta se crea un conjunto de directrices. El estado de una propuesta aplicada incluye at, by que admite valores nulos y target que admite valores nulos; las propuestas descartadas por el sistema pueden incluir un reason.

Revisar el cambio #

change.typeContenido
AddGlossaryTermsourceLocale, sourceText, targetLocale, targetText, description que admite valores nulos y nonTranslatable.
UpdateGlossaryTermtermId, glossaryId que admite valores nulos y los campos de reemplazo proporcionados.
AddRulename, text y targetLocale.
UpdateRuleruleId y los valores proporcionados de name, text o targetLocale.
AddBrandVoiceVariationtargetLocale y text.
UpdateBrandVoiceVariationvariationId y los valores proporcionados de targetLocale o text.

Las propuestas de actualización contienen solo los campos que se van a modificar. Revisa el registro de destino y cualquier uso compartido de su conjunto de directrices antes de aplicar un cambio de amplio alcance.

Aplicar o descartar #

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

Ninguna de las dos solicitudes tiene cuerpo y ambas devuelven la propuesta actualizada. Solo se pueden tomar decisiones sobre propuestas pendientes. Aplicar guarda las directrices propuestas; descartar las deja sin cambios.

Si el destino cambió o ya no existe, intentar aplicar la propuesta puede devolver EngineSuggestionConflicts o EngineSuggestionTargetGone. Actualiza la propuesta y su destino antes de elegir una corrección. Repetir una decisión sobre una propuesta ya resuelta devuelve EngineSuggestionNotPending; si la respuesta no es concluyente, revisa su estado en lugar de repetir la escritura a ciegas.

Decidir sobre varias propuestas #

Envía { "ids": ["FIRST_ID", "SECOND_ID"] } mediante POST a:

  • /v2/engine-suggestions/apply-many: de 1 a 25 ID únicos.
  • /v2/engine-suggestions/dismiss-many: de 1 a 1,000 ID únicos.

Aplicar devuelve applied y failed; descartar devuelve dismissed y failed. Cada entrada fallida contiene id y un error con nombre. Una respuesta HTTP exitosa puede incluir fallas individuales. Los elementos procesados correctamente se conservan aunque otro elemento falle, así que maneja cada resultado de forma independiente.

Usar las directrices revisadas #

Después de aplicar las directrices, revisa el glosario, las reglas o la voz del motor y haz pruebas con contenido representativo. Aplica las directrices aceptadas antes de iniciar el nuevo trabajo. Para actualizar traducciones existentes, selecciona expresamente el contenido y solicita una actualización; aplicar las directrices por sí solo no equivale a solicitar una retraducción.