엔진 제안 API

피드백을 바탕으로 제안을 생성하고, 변경 사항을 확인한 뒤 직접 적용하거나 기각하세요.

엔진 제안은 용어집 용어, 규칙, 브랜드 보이스 변형에 대한 변경 사항을 제시합니다. 적용하기 전에 제안 내용과 적용 대상을 검토하세요. 제안을 생성하면 큐에 추가되고, 적용하면 엔진의 지침이 변경됩니다.

엔진 제안은 Enterprise 요금제에서 제공하는 기능으로 안내되어 있습니다. 호출자에게는 엔진 접근 권한과 관련 제안 권한도 필요합니다. 대시보드에서의 작업 흐름은 큐의 제안을 참고하세요.

아래의 모든 경로는 https://api.lingo.dev 및 API 인증을 사용합니다.

생성 요청 #

엔진에 수집된 피드백으로 제안을 생성하려면:

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

이 요청에는 본문이 없습니다. 피드백을 직접 제공하려면:

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에는 공백이 아닌 내용이 포함되어야 하며, 전체 길이는 10,000자 이하여야 합니다. 이 모드는 제공된 피드백 자체를 바탕으로 제안을 생성하므로, 원하는 수정 사항과 적용할 언어를 포함하세요.

두 경로 모두 HTTP 200과 함께 다음을 반환합니다.

json
{ "enqueued": true }

이 응답은 큐에 제출되었음을 나타내며, 생성이 완료되었다는 뜻은 아닙니다. 처리가 끝나면 엔진의 대기 중인 제안 목록을 조회하세요. 유용한 변경 사항이 없으면 제안이 생성되지 않을 수 있습니다. 요청 직후 조회한 목록이 비어 있다고 해서 요청이 실패한 것은 아닙니다.

제안 목록 조회 #

http
GET /v2/organizations/:orgId/engine-suggestions?engineIds=YOUR_ENGINE_ID&statuses=Pending&limit=25
쿼리 매개변수의미
engineIds조회 범위를 선택한 엔진으로 제한합니다.
targetLocales로캘 범위입니다. 여러 로캘에 공통으로 적용되는 지침을 나타내는 *도 포함합니다.
statusesPending, Applied 또는 Dismissed이며, 기본값은 Pending입니다.
ids지정한 식별자에 해당하는 제안을 조회합니다.
limit1~100 사이의 정수이며, 기본값은 25입니다.
cursor내부 값을 해석하지 않고 그대로 사용하는 페이지네이션 커서입니다.

여러 값을 지정하려면 배열 매개변수를 반복해서 사용하세요. 응답에는 data 및 meta.nextCursor가 포함됩니다. nextCursor 값이 null이 될 때까지 같은 필터로 계속 조회하세요.

각 제안에는 다음이 포함됩니다.

필드의미
id, organizationId, engineId제안의 식별 정보와 소유 정보입니다.
targetLocale제안된 변경 사항의 로캘 범위입니다.
change유형이 지정된 변경 사항입니다. 자세한 내용은 아래에서 설명합니다.
reasoning제안에 대한 설명입니다.
sources점수 평가 결과, 사람이 수정한 내용, 작업 항목 등의 근거를 가리키는 참조입니다.
statustype 값이 Pending, Applied 또는 Dismissed인 객체입니다.
destination변경 사항을 적용할 지침 세트입니다. 사용할 수 없는 경우 null입니다.
createdAt, updatedAtISO 형식의 타임스탬프입니다.

적용 대상에는 kind(Glossary, Ruleset 또는 BrandVoice), 널 값을 허용하는 id, name 및 willCreate이 포함됩니다. 적용 시 지침 세트가 생성되는지 알아보려면 willCreate을 확인하세요. 적용 완료 상태에는 at, 널 값을 허용하는 by 및 널 값을 허용하는 target이 포함됩니다. 시스템에서 기각한 제안에는 reason이 포함될 수 있습니다.

변경 사항 확인 #

change.type내용
AddGlossaryTermsourceLocale, sourceText, targetLocale, targetText, 널 값을 허용하는 description 및 nonTranslatable입니다.
UpdateGlossaryTermtermId, 널 값을 허용하는 glossaryId 및 교체할 값이 제공된 필드입니다.
AddRulename, text 및 targetLocale입니다.
UpdateRuleruleId 및 값이 제공된 name, text 또는 targetLocale입니다.
AddBrandVoiceVariationtargetLocale 및 text입니다.
UpdateBrandVoiceVariationvariationId 및 값이 제공된 targetLocale 또는 text입니다.

업데이트 제안에는 변경할 필드만 포함됩니다. 광범위한 변경을 적용하기 전에 대상 레코드를 확인하고, 해당 지침 세트가 다른 곳에서도 공유되어 사용되는지 살펴보세요.

적용 또는 기각 #

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

두 요청 모두 본문이 없으며, 업데이트된 제안을 반환합니다. 적용 또는 기각 여부는 대기 중인 제안에 대해서만 결정할 수 있습니다. 적용하면 제안된 지침이 기록되고, 기각하면 해당 지침은 변경되지 않습니다.

대상이 변경되었거나 사라진 경우, 적용 요청이 EngineSuggestionConflicts 또는 EngineSuggestionTargetGone를 반환할 수 있습니다. 수정 방법을 선택하기 전에 제안과 대상을 다시 조회하세요. 이미 결정된 제안에 같은 결정을 다시 요청하면 EngineSuggestionNotPending가 반환됩니다. 응답이 불확실할 때는 쓰기 요청을 무작정 반복하지 말고 제안의 상태를 확인하세요.

여러 제안의 적용 또는 기각 결정 #

{ "ids": ["FIRST_ID", "SECOND_ID"] }을 다음 경로로 POST 요청으로 전송하세요.

  • /v2/engine-suggestions/apply-many: 중복 없는 식별자 1~25개.
  • /v2/engine-suggestions/dismiss-many: 중복 없는 식별자 1~1,000개.

적용 요청은 applied 및 failed를 반환하고, 기각 요청은 dismissed 및 failed를 반환합니다. 실패한 각 항목에는 id 및 이름이 지정된 error이 포함됩니다. HTTP 성공 응답에도 개별 항목의 실패가 포함될 수 있습니다. 다른 항목이 실패해도 성공한 항목의 처리 결과는 유지되므로, 각 결과를 개별적으로 처리하세요.

수정된 지침 사용 #

적용 후에는 엔진의 용어집, 규칙 또는 보이스를 확인하고 대표적인 콘텐츠로 테스트하세요. 새 작업을 시작하기 전에 수락한 지침을 적용하세요. 기존 번역을 업데이트하려면 콘텐츠를 직접 선택하고 새로고침을 요청하세요. 지침을 적용하는 것만으로는 재번역이 요청되지 않습니다.