키 제어
값을 원본 콘텐츠, 기존 대상, 번역, 로캘 메타데이터 중 어디에서 가져올지 선택합니다.
카탈로그의 일부 값은 모든 언어에서 동일하게 유지해야 합니다. 반면 사람이 관리하는 대상 값을 사용해야 하는 경우도 있습니다. 키 제어를 사용하면 이를 지원하는 파일 핸들러가 출력을 재구성할 때 각 값을 어떻게 처리할지 명확히 지정할 수 있습니다.
이 옵션은 .lingo/config.json의 파일 항목에 설정합니다. 파일을 선택하거나 키 새로 고침을 요청하지는 않습니다. 이 작업은 번역 범위에서 처리합니다.
| 제어 | 출력 동작 |
|---|---|
lockedKeys | 원본 값을 번역하지 않고 복사합니다. |
preservedKeys | 기존 대상 값이 있으면 그대로 유지합니다. |
ignoredKeys | 이 기능을 지원하는 형식의 출력에서 선택한 콘텐츠를 제거합니다. |
injectLocale | 선택한 위치에 대상 로캘을 기록합니다. |
각 값의 관리 주체 지정하기 #
{
"pattern": "locales/en.json",
"lockedKeys": ["product.id"],
"preservedKeys": ["legal.notice"],
"ignoredKeys": ["internal.note"],
"injectLocale": { "enabled": true, "key": "meta.locale" }
}이 예시에서는 제품 식별자를 원본에서 가져오고, 기존 법적 고지는 대상 값을 유지하며, 내부 메모는 생략합니다. 로캘 주입은 meta.locale에 대상 로캘을 기록하며, 필요한 객체 컨테이너가 없으면 새로 만듭니다. 배열 내 위치를 지정할 때는 기존 배열을 제공하고, 기존 요소나 배열 끝 바로 다음 위치를 선택하세요. 중간에 빈자리를 만들거나 호환되지 않는 값을 통과하는 경로를 지정하면 실패합니다.
보존 기능으로도 사람이 번역한 내용이 없는 곳에 새 번역을 만들 수는 없습니다. 일반적인 증분 작업에서도 기존 대상 콘텐츠를 사용해 키가 변경되지 않은 항목의 수정 사항을 유지합니다. preservedKeys는 여기에 명시적인 보호를 더합니다. 원본이 변경되거나 JSON 키의 이름이 바뀌면 여전히 새로운 작업이 필요할 수 있습니다.
경로와 제어 중첩 #
JSON/JSONC 제어에는 checkout.submit 또는 items[0].title처럼 점으로 구분한 이름과 대괄호 인덱스를 사용합니다. 보호된 경로는 하위 항목까지 포함할 수 있습니다. 키 이름 자체에 점이 포함되어 있으면 $['checkout.submit']처럼 따옴표로 묶은 JSONPath 속성을 사용하세요. lingo push는 이전 CLI에서 /와 함께 작성한 목록도 읽습니다. / 사이의 각 이름을 통째로 처리하므로 checkout/submit는 checkout.submit와 같고, common/error.message는 common 아래의 error.message 키를 가리킵니다. legal/Terms%20of%20use처럼 퍼센트 인코딩된 이름은 디코딩됩니다. /가 없는 패턴은 점 구분 경로로 처리되며 디코딩되지 않으므로, 인코딩된 단일 이름은 $['Terms of use']처럼 JSONPath로 작성하세요. /가 있는 모든 패턴을 이 방식으로 읽으므로, 이름에 /가 포함된 키에는 $.routes['/about'].title처럼 JSONPath를 사용해야 합니다. internal/*처럼 끝에 붙는 *는 이전 CLI와 마찬가지로 internal 바로 아래의 값에 적용되지만, 그 안에 중첩된 객체나 배열에는 적용되지 않습니다. 이전 CLI는 - 또는 .가 이어지는 키도 일치하는 것으로 처리했으므로 legal/terms는 legal/terms-short에도 적용되었습니다. 이제 이러한 접두사 일치는 지원하지 않으므로 해당 키를 별도로 나열하세요. GitHub App은 슬래시 형식을 허용하지 않습니다. 앱에서 같은 구성을 읽는 경우 이 목록을 점 구분 형식이나 JSONPath로 작성하세요. 이 형식에 관한 설명은 범위에서 확인할 수 있습니다.
같은 위치에 무시 규칙이 적용되면 주입된 로캘 값을 포함해 해당 값이 제거됩니다. 로캘 주입은 잠금과 보존보다 우선합니다. 잠금은 보존보다 우선하므로 두 목록에 모두 있는 키는 원본 값을 사용합니다. 상위 항목에 무시 규칙을 적용하면 하위 항목도 제거됩니다. 가능하면 각 값의 관리 주체를 하나만 지정하고, 객체나 배열에서 규칙이 겹치면 출력을 확인하세요.
파일 전체에 강제 실행을 적용하면 서버로 전송되는 현재 대상 산출물이 비워집니다. 이 대상 컨텍스트가 없으면 보존 규칙으로도 사람이 이전에 작성한 문구를 유지할 수 없습니다. 강제로 교체하기 전에 복구 가능한 사본을 보관하세요.
핸들러별 지원 범위 #
JSON과 JSONC는 네 가지 제어 기능을 모두 지원합니다. 타입스크립트, PHP, YAML, 로캘 루트 YAML은 잠금, 보존, 무시를 지원하며, 스트링스딕트는 잠금과 보존을 지원합니다. 자바 속성 파일은 잠금, 보존, 무시, 키 범위를 지원하며, 이전 CLI와 마찬가지로 각 패턴을 키 전체와 대조합니다. CSV는 세 가지 키 규칙 중 어느 것도 지원하지 않습니다. CLI와 GitHub App은 lockedKeys, preservedKeys, ignoredKeys 중 하나라도 설정된 CSV 항목을 거부합니다. 출력 동작은 선택한 형식의 레퍼런스에서 확인하세요.
짧은 경로 형식은 경로 구간 전체에 일치하는 *, 숫자 인덱스, 빈 대괄호를 지원합니다. 부분 와일드카드는 허용하지 않습니다. lingo push를 사용하면 세 가지 키 규칙 목록에서 슬래시 형식도 사용할 수 있습니다. GitHub App과 주입 위치에서는 이 형식을 허용하지 않습니다. 구두점이 포함된 이름을 문자 그대로 지정하려면 따옴표로 묶은 JSONPath 속성을 사용하세요. 명시적인 $ 쿼리는 그대로 전달됩니다. 주입에는 하나의 위치가 필요하며, 활성화 시 기본 키는 language입니다.