API de sugestões de engine
Gere propostas a partir de feedback, examine as alterações e aplique ou descarte cada uma explicitamente.
As sugestões de engine propõem alterações em termos do glossário, regras e variações da voz da marca. Revise o conteúdo proposto e o destino antes de aplicar a proposta. A geração adiciona propostas à Fila; aplicar uma proposta altera as orientações do engine.
As sugestões de engine estão disponíveis no plano Enterprise. Quem faz a chamada também precisa ter acesso ao engine e as permissões correspondentes para sugestões. Consulte Sugestões na Fila para conhecer o workflow no painel.
Todas as rotas abaixo usam https://api.lingo.dev e autenticação de API.
Solicitar geração #
Gere propostas a partir do feedback coletado pelo engine:
POST /v2/engines/:engineId/engine-suggestions/generate
X-API-Key: YOUR_API_KEYEsta requisição não tem corpo. Para fornecer feedback diretamente:
POST /v2/engines/:engineId/engine-suggestions/from-text
Content-Type: application/json
X-API-Key: YOUR_API_KEY{
"text": "In German account settings, use Abonnement for subscription. Avoid Mitgliedschaft for this product feature."
}text deve conter algo além de espaços em branco e ter no máximo 10.000 caracteres. Este modo gera propostas a partir do próprio feedback fornecido, então inclua a correção desejada e o idioma ao qual ela se aplica.
As duas rotas retornam HTTP 200 com:
{ "enqueued": true }Isso confirma o envio à Fila, não a conclusão da geração. Liste as sugestões pendentes do engine após o processamento. A geração pode não produzir propostas quando não há alterações úteis a fazer; uma lista vazia logo após a requisição não indica falha.
Listar propostas #
GET /v2/organizations/:orgId/engine-suggestions?engineIds=YOUR_ENGINE_ID&statuses=Pending&limit=25| Parâmetro de consulta | Significado |
|---|---|
engineIds | Restringir aos engines selecionados. |
targetLocales | Escopos de idioma, incluindo * para orientações que se aplicam a todos os idiomas. |
statuses | Pending, Applied ou Dismissed; o padrão é Pending. |
ids | Recuperar propostas pelos IDs selecionados. |
limit | Número inteiro de 1 a 100; o padrão é 25. |
cursor | Cursor opaco de paginação. |
Repita os parâmetros de array para informar vários valores. A resposta contém data e meta.nextCursor; continue com os mesmos filtros até que nextCursor seja null.
Cada proposta inclui:
| Campo | Significado |
|---|---|
id, organizationId, engineId | Identificação e titularidade da proposta. |
targetLocale | Escopo de idioma da alteração proposta. |
change | Alteração com tipo definido, descrita abaixo. |
reasoning | Justificativa da proposta. |
sources | Referências a evidências, como uma análise feita por um avaliador, uma edição humana ou um item de trabalho. |
status | Objeto cujo type é Pending, Applied ou Dismissed. |
destination | Conjunto de orientações que recebe a alteração, ou null quando indisponível. |
createdAt, updatedAt | Registros de data e hora no formato ISO. |
Um destino inclui kind (Glossary, Ruleset ou BrandVoice), id (que pode ser nulo), name e willCreate. Verifique willCreate para saber se aplicar a proposta cria um conjunto de orientações. O estado de proposta aplicada inclui at, by (que pode ser nulo) e target (que pode ser nulo); propostas descartadas pelo sistema podem incluir um reason.
Examinar a alteração #
change.type | Conteúdo |
|---|---|
AddGlossaryTerm | sourceLocale, sourceText, targetLocale, targetText, description (que pode ser nulo) e nonTranslatable. |
UpdateGlossaryTerm | termId, glossaryId (que pode ser nulo) e os campos de substituição fornecidos. |
AddRule | name, text e targetLocale. |
UpdateRule | ruleId e os valores fornecidos de name, text ou targetLocale. |
AddBrandVoiceVariation | targetLocale e text. |
UpdateBrandVoiceVariation | variationId e o valor fornecido de targetLocale ou text. |
As propostas de atualização contêm apenas os campos que serão alterados. Antes de aplicar uma alteração abrangente, verifique o registro de destino e se o conjunto de orientações dele é usado em outros lugares.
Aplicar ou descartar #
POST /v2/engine-suggestions/:id/applyPOST /v2/engine-suggestions/:id/dismissAs duas requisições não têm corpo e retornam a proposta atualizada. Só é possível decidir sobre propostas pendentes. Aplicar grava as orientações propostas; descartar mantém essas orientações inalteradas.
Se o destino tiver sido alterado ou não existir mais, aplicar a proposta poderá retornar EngineSuggestionConflicts ou EngineSuggestionTargetGone. Atualize a proposta e seu destino antes de escolher uma correção. Repetir uma decisão sobre uma proposta já decidida retorna EngineSuggestionNotPending; se a resposta for incerta, verifique o estado da proposta em vez de repetir a gravação às cegas.
Decidir sobre várias propostas #
Envie { "ids": ["FIRST_ID", "SECOND_ID"] } via POST para:
/v2/engine-suggestions/apply-many: de 1 a 25 IDs únicos./v2/engine-suggestions/dismiss-many: de 1 a 1.000 IDs únicos.
Aplicar retorna applied e failed; descartar retorna dismissed e failed. Cada entrada com falha contém id e um error nomeado. Uma resposta HTTP de sucesso pode incluir falhas individuais. Os itens processados com sucesso são mantidos mesmo quando outro item falha, então trate cada resultado de forma independente.
Usar as orientações revisadas #
Após aplicar as orientações, examine o glossário, as regras ou a voz do engine e teste com conteúdo representativo. Aplique as orientações aceitas antes de iniciar o novo trabalho. Para atualizar traduções existentes, selecione deliberadamente o conteúdo e solicite uma atualização; aplicar orientações, por si só, não equivale a solicitar uma retradução.