번역 파이프라인 구성하기
작업을 시작하기 전에 엔진의 단계 구성을 저장하고, 실제로 실행되는 단계를 확인하세요.
로컬라이제이션 작업은 시작 시점에 저장된 엔진의 파이프라인 구성을 사용합니다. /start 호출 전에 엔진을 구성하세요. 이후 엔진을 수정하면 앞으로 시작하는 작업에만 반영되며, 이미 실행 중인 작업의 구성 스냅샷에는 영향을 주지 않습니다.
Studio에서 엔진의 파이프라인 탭을 열거나 PATCH /v2/engines/:id을 통해 pipelineConfig을 업데이트하세요. 호출자에게는 엔진 편집 권한이 필요합니다. 조직에는 실행 가능한 각 단계에서 요구하는 기능의 이용 권한이 있어야 합니다. 기능 이용 권한과 요금을 참고하세요.
전체 구성 저장하기 #
기존 구성을 변경하기 전에 GET /v2/engines/:id으로 엔진을 조회하세요. pipelineConfig을 전송하면 기존 구성이 대체되고, 생략된 단계에는 기본값이 적용됩니다. 계속 사용할 설정은 빠뜨리지 마세요.
이 요청은 번역 후 표현을 다듬는 단계를 실행하도록 구성합니다. 요청에서 생략된 선택적 단계는 비활성화됩니다.
PATCH /v2/engines/:id
Content-Type: application/json
X-API-Key: YOUR_API_KEY{
"pipelineConfig": {
"localize": { "enabled": true },
"rephrase": { "enabled": true }
}
}애플리케이션에서 특정 유형의 작업에 다른 정책을 적용해야 한다면 별도의 엔진을 사용하세요. 해당 엔진의 모델과 지침을 구성한 다음, 그 유형의 작업을 생성할 때 해당 엔진의 식별자를 선택하세요.
단계 설정 #
pipelineConfig의 필드 | 설정 |
|---|---|
localize | enabled: true. 번역은 필수입니다. |
preEdit, rephrase, postEdit, backTranslation | enabled 불리언 값. 기본값은 거짓입니다. |
qualityGate | enabled 불리언 및 strictness: "strict", "medium" 또는 "lax" (기본값 "medium"). |
humanEdit | enabled, 양의 정수 timeoutHours(기본값 48), 검토 routes. |
contentLength | enabled과 아래에 설명된 mode. |
후편집에는 휴먼 리뷰가 필요합니다. 후편집은 사람이 검토한 결과물을 대상으로 실행되므로, 검토를 건너뛰거나 제한 시간이 초과되면 다듬을 결과물이 없을 수 있습니다.
콘텐츠 길이 모드는 { "_tag": "noLongerThanSource" }(기본값), { "_tag": "fixedCap", "maxColumns": 40 } 또는 { "_tag": "matchSource", "tolerancePct": 10 }입니다. 숫자 값은 양의 정수여야 합니다. 이 값은 화면에 표시되는 열 수의 목표값일 뿐, 바이트 수 제한이 아니며 사용자 인터페이스에 맞게 표시된다고 보장하지도 않습니다.
휴먼 리뷰 라우팅하기 #
먼저 결정 풀을 만들거나 선택하세요. 각 humanEdit.routes 항목은 풀 이름과 해당 풀에 적용할 언어 및 디렉터리 범위를 지정합니다. 다음 구성은 새로 번역된 모든 콘텐츠를 하나의 풀로 보냅니다.
{
"pipelineConfig": {
"localize": { "enabled": true },
"humanEdit": {
"enabled": true,
"timeoutHours": 48,
"routes": [
{
"pool": "YOUR_DECISION_POOL_ID",
"match": { "locales": [] }
}
]
}
}
}locales 배열이 비어 있으면 모든 언어에 적용됩니다. match 안에 "path": ["emails/**"]을 추가하면 해당 디렉터리 아래의 문서에 적용되며, 문서의 key을 기준으로 일치 여부를 확인합니다. 경로는 실제 디렉터리 이름 뒤에 /**을 붙여 지정합니다. path이 없는 라우팅은 모든 디렉터리에 적용됩니다. 디렉터리와 로캘이 더 구체적으로 일치하는 라우팅이 우선하며, 서로 충돌하는 라우팅은 거부됩니다.
원하는 번역만 검토하려면 휴먼 리뷰를 활성화하고 검토 대상 번역을 포함하는 경로를 추가하세요. pipelineConfig 안에 qualityGate을 추가하고 나머지 설정은 그대로 유지하세요:
{
"qualityGate": { "enabled": true, "strictness": "medium" }
}humanEdit.enabled이 false인 상태에서도 활성화된 qualityGate을 저장할 수 있습니다. Studio는 휴먼 리뷰를 껐다가 다시 켜도 저장된 설정을 유지합니다. API를 사용할 때는 설정이 유지되도록 교체하는 각 pipelineConfig에 qualityGate를 포함하세요. 게이트는 작업에 최종 적용되는 파이프라인에서 휴먼 리뷰가 활성화된 경우에만 작동합니다.
게이트는 각 단위의 발견 사항을 저장합니다. "strict"은 발견 사항이 하나라도 있으면, "medium"는 심각도가 주요 또는 치명적 수준인 발견 사항이 있으면, "lax"은 치명적 수준인 발견 사항이 있을 때만 검토를 요구합니다. 게이트가 확인하지 못한 번역도 검토가 필요합니다. 전체를 선택하려면 qualityGate.enabled을 false로 설정하세요. 그러면 라우팅 범위에 해당하는 모든 새 번역이 검토 대상으로 전달됩니다. 재사용된 번역은 새 검토 작업으로 생성되지 않습니다.
판정 자체는 엄격도에 따라 달라지지 않으며, 설정한 수준은 발견 사항에 적용됩니다. 엔진의 수준을 변경하면 앞으로 시작하는 작업에만 반영되고, 이미 실행 중인 작업에 저장된 구성에는 영향을 주지 않습니다. 각 수준의 설명과 심각도 정의는 품질 게이트 수준을 참고하세요.
기존 비동기 로컬라이제이션 API는 여전히 humanEdit.qualityThreshold을 받지만 무시합니다. 휴먼 리뷰 대상으로 선택된 언어의 모든 번역은 검토자에게 전달됩니다. 현재 파이프라인에서 선택적으로 검토하려면 엔진의 휴먼 리뷰 설정에서 검토 수준을 설정하세요.
검토 이용 가능 여부는 조직의 요금제와 풀의 제공업체 연결 상태에 따라 달라집니다. 작업이 시작되면 이용할 수 없는 단계 기능과 이에 의존하는 단계가 함께 비활성화됩니다. 실제로 적용되는 워크플로를 확인하려면 작업의 대상 단계를 조회하세요. 게시에 사람의 결정이 필요하다면 다운로드한 결과물을 전달하기 전에 반드시 해당 정책을 적용하세요.
결과 확인하기 #
품질 게이트 단계는 확인한 각 단위에 대해 다음 출력을 저장합니다.
{
"findings": [
{
"span": "Pay €20",
"reason": "The translation changes the source amount from €10 to €20.",
"category": "accuracy",
"severity": "critical"
}
]
}span은 게이트가 판정한 번역에서 그대로 인용한 내용입니다. reason은 영어 문장 하나입니다. 범주는 accuracy, terminology, guidance, fluency, style이며, 심각도는 critical, major, minor입니다. findings 배열이 비어 있으면 게이트가 발견한 오류가 없다는 뜻입니다. 검토 단위는 이 출력을 quality로 반환합니다. 휴먼 리뷰를 참고하세요. 검토자는 큐에서 번역 옆에 표시된 발견 사항을 확인할 수 있습니다.
단계 진행 상황에서는 완료된 작업, 건너뛴 작업, 실패한 작업, 경고가 발생한 작업을 구분합니다. 휴먼 리뷰에서는 결정과 기한을 설명합니다. 파이프라인 가이드에서는 각 단계가 어떤 점에서 유용한지, 후속 단계가 이전 단계의 텍스트를 어떻게 변경할 수 있는지 설명합니다.