API des Suggestions du moteur

Générez des propositions à partir des retours, examinez les modifications proposées, puis appliquez-les ou rejetez-les explicitement.

Les suggestions du moteur proposent des modifications aux termes du glossaire, aux règles et aux variantes de voix de marque. Examinez le contenu proposé et sa destination avant de l’appliquer. La Génération ajoute des propositions à la file d’attente ; appliquer une proposition modifie les consignes du moteur.

La fonctionnalité Suggestions du moteur est disponible avec l’offre Enterprise. L’appelant doit également avoir accès au moteur et disposer des autorisations nécessaires pour les suggestions. Consultez Suggestions dans la file d’attente pour découvrir le workflow dans le tableau de bord.

Toutes les routes ci-dessous utilisent https://api.lingo.dev et l’authentification API.

Demander une génération #

Générez des propositions à partir des retours recueillis par le moteur :

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

Cette requête ne contient aucun corps. Pour fournir directement des retours :

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 doit contenir au moins un caractère autre qu’un caractère d’espacement et ne pas dépasser 10 000 caractères. Ce mode génère des propositions à partir des retours fournis eux-mêmes ; précisez donc la correction souhaitée et la langue à laquelle elle s’applique.

Les deux routes renvoient un code HTTP 200 avec :

json
{ "enqueued": true }

Cette réponse confirme l’ajout à la file d’attente, pas la fin de la génération. Listez les suggestions en attente du moteur une fois le traitement terminé. La Génération peut ne produire aucune proposition s’il n’y a aucune modification utile à apporter ; une liste vide immédiatement après la requête ne signifie pas que celle-ci a échoué.

Lister les propositions #

http
GET /v2/organizations/:orgId/engine-suggestions?engineIds=YOUR_ENGINE_ID&statuses=Pending&limit=25
Paramètre de requêteSignification
engineIdsLimiter les résultats aux moteurs sélectionnés.
targetLocalesPérimètres par langue, dont * pour les consignes qui s’appliquent à toutes les langues.
statusesPending, Applied ou Dismissed ; valeur par défaut : Pending.
idsRécupérer les propositions correspondant aux identifiants sélectionnés.
limitEntier de 1 à 100 ; valeur par défaut : 25.
cursorCurseur de pagination opaque.

Répétez les paramètres de type tableau pour fournir plusieurs valeurs. La réponse contient data et meta.nextCursor ; poursuivez avec les mêmes filtres jusqu’à ce que nextCursor soit null.

Chaque proposition comprend :

ChampSignification
id, organizationId, engineIdIdentité et propriétaire de la proposition.
targetLocalePérimètre linguistique de la modification proposée.
changeModification typée, décrite ci-dessous.
reasoningExplication de la proposition.
sourcesRéférences aux éléments justificatifs, comme une évaluation par un outil de notation, une modification humaine ou un élément de travail.
statusObjet dont type est Pending, Applied ou Dismissed.
destinationEnsemble de consignes auquel la modification s’applique, ou null s’il n’est pas disponible.
createdAt, updatedAtHorodatages au format ISO.

Une destination comprend kind (Glossary, Ruleset ou BrandVoice), id pouvant être nul, name et willCreate. Vérifiez willCreate pour savoir si l’application de la proposition crée un ensemble de consignes. Le statut appliqué comprend at, by pouvant être nul et target pouvant être nul ; les propositions rejetées par le système peuvent inclure un reason.

Examiner la modification #

change.typeContenu
AddGlossaryTermsourceLocale, sourceText, targetLocale, targetText, description pouvant être nul et nonTranslatable.
UpdateGlossaryTermtermId, glossaryId pouvant être nul et les champs de remplacement fournis.
AddRulename, text et targetLocale.
UpdateRuleruleId et les champs name, text ou targetLocale fournis.
AddBrandVoiceVariationtargetLocale et text.
UpdateBrandVoiceVariationvariationId et les champs targetLocale ou text fournis.

Les propositions de mise à jour ne contiennent que les champs à modifier. Vérifiez l’enregistrement cible et les éventuels usages partagés de son ensemble de consignes avant d’appliquer une modification de grande portée.

Appliquer ou rejeter #

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

Les deux requêtes ne contiennent aucun corps et renvoient la proposition mise à jour. Seules les propositions en attente peuvent faire l’objet d’une décision. Appliquer une proposition enregistre les consignes proposées ; la rejeter laisse ces consignes inchangées.

Si la cible a changé ou a disparu, l’application peut renvoyer EngineSuggestionConflicts ou EngineSuggestionTargetGone. Actualisez la proposition et sa cible avant de choisir une correction. Répéter une décision sur une proposition ayant déjà fait l’objet d’une décision renvoie EngineSuggestionNotPending ; après une réponse incertaine, examinez son état plutôt que de répéter l’écriture à l’aveugle.

Statuer sur plusieurs propositions #

Envoyez { "ids": ["FIRST_ID", "SECOND_ID"] } par POST à :

  • /v2/engine-suggestions/apply-many : de 1 à 25 identifiants uniques.
  • /v2/engine-suggestions/dismiss-many : de 1 à 1 000 identifiants uniques.

L’application renvoie applied et failed ; le rejet renvoie dismissed et failed. Chaque entrée en échec contient id et un error nommé. Une réponse HTTP indiquant un succès peut inclure des échecs individuels. Les éléments traités avec succès sont conservés même si un autre élément échoue ; traitez donc chaque résultat indépendamment.

Utiliser les consignes révisées #

Après l’application, examinez le glossaire, les règles ou la voix de marque du moteur et testez du contenu représentatif. Appliquez les consignes acceptées avant de lancer la nouvelle tâche. Pour mettre à jour des traductions existantes, sélectionnez délibérément le contenu et demandez une actualisation ; appliquer les consignes ne constitue pas, à lui seul, une demande de retraduction.