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:
POST /v2/engines/:engineId/engine-suggestions/generate
X-API-Key: YOUR_API_KEYEste pedido não tem corpo. Para fornecer comentários 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 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:
{ "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 #
GET /v2/organizations/:orgId/engine-suggestions?engineIds=YOUR_ENGINE_ID&statuses=Pending&limit=25| Parâmetro de consulta | Significado |
|---|---|
engineIds | Restringir aos motores selecionados. |
targetLocales | Âmbitos de idioma, incluindo * para orientações aplicáveis a todos os idiomas. |
statuses | Pending, Applied ou Dismissed; o valor predefinido é Pending. |
ids | Obter os IDs de proposta selecionados. |
limit | Número inteiro de 1 a 100; o valor predefinido é 25. |
cursor | Cursor 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:
| Campo | Significado |
|---|---|
id, organizationId, engineId | Identificação e titularidade da proposta. |
targetLocale | Âmbito de idioma da alteração proposta. |
change | Alteração com tipo definido, descrita abaixo. |
reasoning | Explicação da proposta. |
sources | Referências que fundamentam a proposta, como uma avaliação de 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 se não estiver disponível. |
createdAt, updatedAt | Marcas 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.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 para name, text ou targetLocale. |
AddBrandVoiceVariation | targetLocale e text. |
UpdateBrandVoiceVariation | variationId 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 #
POST /v2/engine-suggestions/:id/applyPOST /v2/engine-suggestions/:id/dismissNenhum 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.