실제 페이로드는 좀처럼 전부 설명문으로만 이루어지지 않습니다. title와 body를 담고 있는 같은 객체 안에는 id, slug, asset URL, 템플릿 이름, enum 코드처럼 콘텐츠를 식별하거나 연결하는 값도 함께 들어 있습니다. 이런 값은 번역을 거친 뒤에도 들어온 그대로 정확히 유지되어야 합니다. 문제는 조용히 생깁니다. 모델이 번역할 텍스트 옆에 id라는 필드를 보면, "post-42"가 현지화된 형태가 더 낫다고 판단하거나 URL을 정규화하거나 enum을 "수정"할 수 있습니다. 식별자 하나만 바뀌어도 링크가 깨지거나 프로덕션 조회가 실패할 수 있고, 그 문제는 모델이 굳이 친절을 베풀려 한 로캘에서 터집니다.
lockedKeys는 이런 추측의 여지를 없애 줍니다. 바뀌면 안 되는 키를 정확한 이름이나 glob으로 지정하면 로컬라이제이션 엔진이 해당 값을 번역에서 제외한 뒤, 모든 대상 로캘의 outputData에 원본 값을 그대로 다시 병합합니다. 잠긴 값은 번역되지도, 정규화되지도, 재작성되지도 않습니다. 어떤 로캘이든 들어간 식별자는 그대로 나옵니다.
lockedKeys는 create-jobs 요청의 필드입니다. 전체 요청 형식과 202 응답은 Create jobs에서 확인하세요. 이 페이지에서는 lockedKeys에 무엇을 넣어야 하는지와 매칭이 어떻게 동작하는지만 다룹니다.
이름으로 키 잠그기#
lockedKeys를 data와 함께 전달하세요. 각 항목은 패턴이며, 가장 단순한 형태는 보존하려는 키의 이름 그 자체입니다.
{
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"data": {
"id": "post-42",
"title": "How async APIs reduce latency",
"tags": ["performance", "infra"],
"author": { "id": "u_abc", "name": "Sam" },
"body": "Async APIs let your app stay responsive while translations process in the background."
},
"lockedKeys": ["id"]
}가장 단순한 패턴 id는 완전한 세그먼트로 등장하는 모든 id 키와 매칭됩니다. 여기서는 최상위 id와 중첩된 author.id가 모두 해당됩니다. 모든 독일어 및 프랑스어 작업의 outputData는 "post-42"와 "u_abc"를 정확히 유지합니다. 번역되는 것은 title, name, body뿐입니다. tags는 잠긴 경로를 포함하지 않으므로 그대로 두며, 그 안의 문자열 값은 다른 텍스트와 마찬가지로 번역됩니다.
마지막 포인트는 분명히 짚고 넘어갈 필요가 있습니다. 회의적인 사람이 가장 먼저 던지는 질문에 대한 답이기 때문입니다.
잠긴 값도 번역되나요?
아니요. lockedKeys에 지정한 키는 번역에서 제외되며, 모든 대상 로캘의 outputData에 원본 값이 그대로 병합됩니다. 보낸 값은 변경 없이 그대로 돌아옵니다. 번역되지도, 정규화되지도, 재작성되지도 않습니다. 잠금은 모델이 따르길 기대하는 힌트가 아니라, lockedKeys를 통해 결과를 보장하는 장치입니다.
어디서든 이름으로 매칭하거나, 위치로 정밀하게 지정하기#
단순 패턴은 키 이름이며, 트리 어디에서든, 어떤 깊이에서든, 완전한 세그먼트로 그 이름과 매칭됩니다. audioSrc가 서로 다른 부모 아래 열두 곳에 중첩되어 나타나더라도, 패턴 audioSrc 하나로 열두 곳 모두를 잠글 수 있습니다. 모든 발생 위치를 잡으려고 경로를 일일이 나열할 필요는 없습니다. 대부분의 경우 이 한 줄이면 충분합니다.
위치 기준으로 더 세밀하게 제어해야 할 때도 있습니다. 예를 들어 어떤 위치의 한 번만 잠그고 다른 위치는 잠그지 않거나, 배열의 모든 요소만 잠그고 나머지는 그대로 두고 싶다면 /를 경로 구분자로 쓰는 glob을 사용하세요. 배열 인덱스도 일반 세그먼트처럼 취급되므로 users/0/email와 users/*/email는 모두 유효한 경로입니다.
| 패턴 | 잠그는 대상 |
|---|---|
audioSrc | 트리의 어느 깊이에서든 나타나는 모든 audioSrc 리프 |
metadata | 어디에 나타나든 전체 metadata 하위 트리 |
metadata/author | 어디에 나타나든 해당 metadata/author 시퀀스와 그 아래 전체 |
users/*/email | 모든 사용자의 email — *는 하나의 세그먼트이며 모든 인덱스와 매칭됩니다 |
users/0/email | 첫 번째 사용자의 이메일만 |
**/{audioSrc,imageSrc} | 중괄호 대체로 두 리프 이름 모두 |
위의 두 패턴은 의도적으로 단일 리프보다 더 넓은 범위를 잠급니다. metadata는 해당 키 아래의 전체 하위 트리를 잠급니다. 번역 가능한 것처럼 보이든 아니든 그 아래의 모든 값이 보존됩니다. metadata/author는 해당 시퀀스가 나타나는 모든 위치를 그 아래 전체와 함께 잠급니다. 전체 블록이 구조적인 경우, 예를 들어 config 객체나 원시 embed라면 하위 트리 잠금을 선택하세요. 반대로 번역 가능한 블록 안에서 특정 필드 하나만 그대로 유지해야 한다면 리프 잠금(metadata/author/name)이 적합합니다.
regex가 아니라 glob입니다
*는 정확히 하나의 경로 세그먼트와 매칭되고, **는 임의 개수의 세그먼트에 걸쳐 매칭되며, {a,b}는 여러 대안을 중괄호로 나열하는 방식입니다. 문자 클래스나 토큰 일부 매칭은 지원하지 않습니다. 패턴은 부분 문자열이 아니라 전체 경로 세그먼트 단위로 동작합니다. 정규식이 아니라 users/*/email처럼 작성하세요.
반환되는 결과#
잠금은 모델이 무엇을 번역할지는 바꾸지만, 결과의 형태 자체는 바꾸지 않습니다. outputData는 입력 구조를 정확히 그대로 반영합니다. 잠긴 키는 원래 위치에 원래 값을 유지하고, 그 주변의 번역 가능한 문자열만 번역됩니다. 누락되거나, 이름이 바뀌거나, 순서가 바뀌는 일은 없습니다.
위 입력의 경우 모든 로캘의 outputData에는 id: "post-42"와 author.id: "u_abc"가 변경 없이 유지되고, title, name, body는 대상 언어로 제공됩니다. 전체 작업 응답인 outputData, 단계별 steps, 상태는 Get a single job에 문서화되어 있습니다.
먼저 알아둘 한 가지 제한#
lockedKeys는 요청당 최대 100개의 패턴까지 받을 수 있습니다. 이는 패턴 수의 상한이지, 그 패턴이 매칭하는 키 수의 상한은 아닙니다. 단일 audioSrc 또는 users/*/email만으로도 큰 페이로드 전반에서 수천 개의 값을 잠글 수 있으며, 이 경우에도 패턴 하나로 계산됩니다. 서로 다른 패턴이 100개에 가까워지고 있다면, 대개는 더 넓은 glob(**/{id,slug,href})이나 하위 트리 잠금으로 같은 의도를 훨씬 적은 줄 수로 표현할 수 있다는 신호입니다.
lockedKeys는 요청 단위로, 필요할 때만 적용하는 설정입니다. 즉 이 작업 그룹에만 키 잠금이 적용됩니다. 따라서 어떤 작업에서도 절대 번역되면 안 되는 용어, 예를 들어 제품명, 상표 등록된 기능명, 문자 그대로 유지해야 하는 단위처럼 항상 고정되어야 하는 항목은 엔진의 glossary에 번역 제외 항목으로 두는 편이 맞습니다. 그러면 모든 호출에 자동으로 적용됩니다. Glossaries를 참고하세요. 특정 페이로드 구조에 묶인 필드에는 lockedKeys를 사용하고, 모든 콘텐츠에서 공통으로 유지되어야 하는 어휘에는 glossary를 사용하세요.
