API de sugerencias del motor

Genera propuestas a partir de comentarios, examina los cambios que proponen 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 variantes de la voz de marca. Revisa el contenido propuesto y su destino antes de aplicarlo. La generación añade propuestas a la Cola; al aplicar una propuesta, se modifican las directrices del motor.

Las sugerencias del motor están disponibles con 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 del panel.

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

Solicitar la 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 contener algo más que espacios en blanco y no superar los 10.000 caracteres. Este modo genera propuestas a partir de los propios 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 finalizado. Consulta las sugerencias pendientes del motor una vez terminado el procesamiento. La generación puede no producir ninguna propuesta si no hay cambios útiles que hacer; obtener una lista vacía inmediatamente después no indica 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.
idsRecupera los ID de las propuestas seleccionadas.
limitEntero de 1 a 100; el valor predeterminado es 25.
cursorCursor de paginación opaco.

Repite los parámetros de tipo matriz para indicar 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 que respaldan la propuesta, como una evaluació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 un valor nulo, name y willCreate. Comprueba 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 un valor nulo y target que admite un valor nulo; las propuestas descartadas por el sistema pueden incluir un reason.

Examinar el cambio #

change.typeContenido
AddGlossaryTermsourceLocale, sourceText, targetLocale, targetText, description que admite un valor nulo y nonTranslatable.
UpdateGlossaryTermtermId, glossaryId que admite un valor nulo y los campos de sustitución 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. Comprueba 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

Ambas solicitudes no tienen cuerpo y devuelven la propuesta actualizada. Solo se puede decidir sobre propuestas pendientes. Al aplicar una propuesta, se guardan las directrices propuestas; al descartarla, esas directrices no cambian.

Si el destino ha cambiado o ha desaparecido, al aplicar la propuesta se 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; comprueba su estado si la respuesta no es concluyente, en lugar de repetir la operación de 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 correcta puede incluir fallos individuales. Los elementos procesados correctamente se conservan aunque falle otro elemento, así que gestiona cada resultado de forma independiente.

Usar las directrices revisadas #

Después de aplicar las directrices, examina el glosario, las reglas o la voz del motor y prueba 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 nueva traducción.