API de sugestões do motor

Gere propostas a partir de comentários, analise as alterações e aplique-as ou rejeite-as explicitamente.

As sugestões do motor propõem alterações a termos do glossário, regras e variações da voz da marca. Reveja o conteúdo proposto e o respetivo destino antes de o aplicar. A geração adiciona propostas à fila; aplicar uma proposta altera as orientações do motor.

As sugestões do motor estão disponíveis no plano Enterprise. Quem faz a chamada também precisa de acesso ao motor e das permissões necessárias para gerir sugestões. Consulte Sugestões na fila para conhecer o workflow no painel.

Todas as rotas abaixo utilizam https://api.lingo.dev e autenticação da API.

Solicitar a geração #

Gere propostas a partir dos comentários recolhidos pelo motor:

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

Este pedido não tem corpo. Para fornecer comentários diretamente:

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 tem de conter pelo menos um caráter que não seja um espaço em branco e não pode exceder 10 000 caracteres. Este modo gera propostas a partir dos próprios comentários fornecidos, pelo que deve incluir a correção pretendida e o idioma a que se aplica.

Ambas as rotas devolvem HTTP 200 com:

json
{ "enqueued": true }

Esta resposta confirma a entrada na fila, não a conclusão da geração. Após o processamento, liste as sugestões pendentes do motor. A geração pode não produzir propostas se não houver alterações úteis a fazer; uma lista vazia obtida de imediato não significa que o pedido tenha falhado.

Listar propostas #

http
GET /v2/organizations/:orgId/engine-suggestions?engineIds=YOUR_ENGINE_ID&statuses=Pending&limit=25
Parâmetro de consultaSignificado
engineIdsRestringir aos motores selecionados.
targetLocalesÂmbitos de idioma, incluindo * para orientações aplicáveis a todos os idiomas.
statusesPending, Applied ou Dismissed; o valor predefinido é Pending.
idsObter os IDs de proposta selecionados.
limitNúmero inteiro de 1 a 100; o valor predefinido é 25.
cursorCursor de paginação opaco.

Para indicar vários valores, repita os parâmetros de matriz. A resposta contém data e meta.nextCursor; continue com os mesmos filtros até que nextCursor seja null.

Cada proposta inclui:

CampoSignificado
id, organizationId, engineIdIdentificação e titularidade da proposta.
targetLocaleÂmbito de idioma da alteração proposta.
changeAlteração com tipo definido, descrita abaixo.
reasoningExplicação da proposta.
sourcesReferências que fundamentam a proposta, como uma avaliação de um avaliador, uma edição humana ou um item de trabalho.
statusObjeto cujo type é Pending, Applied ou Dismissed.
destinationConjunto de orientações que recebe a alteração, ou null se não estiver disponível.
createdAt, updatedAtMarcas temporais ISO.

Um destino inclui kind (Glossary, Ruleset ou BrandVoice), id que pode ser nulo, name e willCreate. Consulte willCreate para saber se a aplicação da proposta cria um conjunto de orientações. O estado de aplicação inclui at, by que pode ser nulo e target que pode ser nulo; as propostas rejeitadas pelo sistema podem incluir um reason.

Analisar a alteração #

change.typeConteúdo
AddGlossaryTermsourceLocale, sourceText, targetLocale, targetText, description que pode ser nulo e nonTranslatable.
UpdateGlossaryTermtermId, glossaryId que pode ser nulo e os campos de substituição fornecidos.
AddRulename, text e targetLocale.
UpdateRuleruleId e os valores fornecidos para name, text ou targetLocale.
AddBrandVoiceVariationtargetLocale e text.
UpdateBrandVoiceVariationvariationId e o valor fornecido para targetLocale ou text.

As propostas de atualização contêm apenas os campos a alterar. Antes de aplicar uma alteração abrangente, verifique o registo de destino e se o respetivo conjunto de orientações é utilizado noutros contextos.

Aplicar ou rejeitar #

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

Nenhum dos pedidos tem corpo e ambos devolvem a proposta atualizada. Só é possível decidir sobre propostas pendentes. Aplicar grava as orientações propostas; rejeitar mantém essas orientações inalteradas.

Se o destino tiver sido alterado ou já não existir, a aplicação pode devolver EngineSuggestionConflicts ou EngineSuggestionTargetGone. Atualize a proposta e o respetivo destino antes de escolher uma correção. Repetir uma decisão sobre uma proposta já decidida devolve EngineSuggestionNotPending; se a resposta não for conclusiva, verifique o estado da proposta em vez de repetir a operação de escrita sem verificar.

Decidir sobre várias propostas #

Envie { "ids": ["FIRST_ID", "SECOND_ID"] } por POST para:

  • /v2/engine-suggestions/apply-many: 1–25 IDs únicos.
  • /v2/engine-suggestions/dismiss-many: 1–1 000 IDs únicos.

A aplicação devolve applied e failed; a rejeição devolve dismissed e failed. Cada entrada com falha contém id e um error identificado pelo nome. Uma resposta HTTP de sucesso pode incluir falhas individuais. Os itens processados com sucesso são mantidos mesmo que outro item falhe, pelo que deve tratar cada resultado de forma independente.

Utilizar as orientações revistas #

Após aplicar as orientações, analise o glossário, as regras ou a voz do motor e teste com conteúdo representativo. Aplique as orientações aceites antes de iniciar a nova tarefa. Para atualizar traduções existentes, selecione deliberadamente o conteúdo e solicite uma atualização; aplicar orientações, por si só, não constitui um pedido de retradução.