JSON
중첩된 문자열 값을 번역하고, 경로별로 복사, 유지, 제외 또는 업데이트 여부를 제어하세요.
JSON 카탈로그에서 애플리케이션은 키를 조회해 해당 값을 표시합니다. json 파일 처리기는 객체 키, 배열 위치, 숫자, 불리언, 널 값은 데이터로 유지하고 문자열 값만 변경합니다. 현재 원본을 바탕으로 대상을 재구성하면서 새 번역이나 유지할 기존 대상 텍스트를 삽입합니다.
이 처리기는 중첩된 객체와 배열로 구성된 카탈로그는 물론, 루트에 있는 단일 문자열도 지원합니다. CLI는 .json에서 json을 추론합니다. CLI 설정 또는 GitHub App에서 원본을 설정하세요.
번역 작업으로 처리되는 항목 #
예를 들면 다음과 같습니다.
{
"checkout": {
"title": "Complete your order",
"delivery": "Delivery within {days} days"
},
"plans": [
{ "name": "Personal", "seats": 1 },
{ "name": "Team", "seats": 10 }
],
"enabled": true
}처리기는 checkout.title, checkout.delivery, plans[0].name, plans[1].name를 선택합니다. seats의 숫자와 enabled의 불리언은 변경하지 않습니다. 문자열로 된 식별자는 명시적으로 보호하세요. 값의 JSON 자료형은 해당 값이 텍스트라는 사실만 알려 줄 뿐, 사람이 읽도록 작성된 값인지는 알려 주지 않습니다.
축약 경로 형식에서는 점으로 객체를 탐색하고 대괄호로 배열 위치를 지정합니다. checkout.title는 중첩된 값을, plans[0].name는 첫 번째 요금제의 이름을 선택합니다. 키 이름 자체가 checkout.title인 경우에는 따옴표를 사용하는 JSONPath 형식인 $['checkout.title']를 사용하세요. 선택 구문은 키 제어를 참고하세요.
업데이트 시 기존 번역을 재사용하는 방식 #
증분 실행에는 서로 다른 세 가지 입력이 사용됩니다.
| 입력 | 역할 |
|---|---|
| 현재 원본 | 새 출력의 구조와 문자열을 정의합니다. |
| 이전 원본 | 동일한 경로의 원본 문자열이 변경되었는지 판단하는 기준이 됩니다. |
| 기존 대상 | 유지할 수 있는 번역을 제공합니다. |
이전 원본과 기존 대상이 있으면 새로 추가되거나 변경된 원본 문자열이 번역 작업으로 처리됩니다. 원본 문자열이 변경되지 않았다면 해당 경로의 기존 대상 값을 재사용할 수 있습니다. 두 키의 영어 텍스트가 같아도 별개의 레코드로 유지됩니다. 맥락이 다르면 승인된 번역도 다를 수 있기 때문입니다.
예를 들어 checkout.title를 변경했다고 해서 checkout.delivery까지 다시 번역해야 하는 것은 아닙니다. 후자의 원본 값이 그대로이고 대상 값이 있다면 해당 대상 값을 계속 사용할 수 있습니다. 새로 번역할 문자열이 없더라도 숫자나 기타 구조 데이터가 변경되면 파일을 재구성해야 할 수 있습니다.
이전 원본과 승인된 대상은 한 쌍으로 보관하세요. 둘 중 하나라도 없으면 처리기는 문자열을 처음 처리하는 것으로 간주합니다. CLI의 Lockfile 및 캐시는 실행 간에 이러한 입력을 연결합니다.
보호된 경로의 처리 방식 선택 #
각 제어 방식에 따라 출력 결과가 달라집니다.
| 제어 방식 | 번역 동작 | 출력 동작 |
|---|---|---|
| 잠금 경로 | 번역에서 제외됩니다. | 현재 원본의 값을 가져옵니다. |
| 보존 경로 | 번역에서 제외됩니다. | 기존 대상에 해당 경로가 있으면 그 값을 유지하고, 없으면 원본 값을 유지합니다. |
| 무시 경로 | 번역에서 제외됩니다. | 생성되는 대상에서 해당 경로를 제거합니다. |
| 로캘 주입 | 설정된 로캘 필드는 번역에서 제외됩니다. | 해당 필드에 대상 로캘을 기록합니다. |
모든 로캘에서 원본 값을 사용해야 하는 공유 식별자는 잠금으로 설정하세요. 로캘마다 연결 대상이 다른 대상별 URL은 보존으로 설정하세요. 번역된 파일에 포함되면 안 되는 원본 전용 메모는 무시로 설정하세요. 이 설정들은 모두 단순히 “번역하지 않음”과 같은 뜻이 아닙니다.
같은 경로에서는 잠금이 보존보다 우선하므로, 두 목록에 모두 포함된 값은 원본에서 가져옵니다. 무시로 설정된 값은 잠금, 보존 또는 로캘 주입 대상으로도 지정되어 있더라도 제거됩니다. 로캘 주입은 해당 위치의 잠금과 보존보다 우선합니다. 값마다 하나의 제어 방식만 지정하는 것이 좋습니다. 객체나 배열에 걸쳐 규칙이 겹치면 출력을 확인하세요.
배열 요소를 제거하면 뒤에 있는 요소들의 위치가 바뀝니다. 결과 배열은 번역된 텍스트뿐 아니라 데이터로서도 검토하세요. 로캘 주입 시 누락된 객체 컨테이너가 생성될 수 있습니다. 배열에 값을 쓸 때는 기존 요소의 위치나 배열 끝 바로 다음 위치를 사용하세요. 중간에 빈자리를 만들거나 호환되지 않는 값을 거쳐야 하는 경로에 쓰려고 하면 실패합니다.
CLI 파일 항목 필드 또는 GitHub 파일 항목 옵션에서 이러한 제어 방식을 설정하세요.
적용 범위와 재구성의 제약 #
키 새로고침은 선택한 번역을 기존 대상에 병합합니다. 선택하지 않은 대상 값, 대상에만 있는 키, 생략된 항목은 그대로 유지됩니다. 범위 밖에 있는 원본 전용 키는 추가되지 않습니다. 배열에 값을 쓸 때는 중간에 빈자리가 생기면 안 됩니다. 예를 들어 두 번째 배열 요소를 선택해도 누락된 첫 번째 요소가 자동으로 채워지지는 않습니다. 부분 업데이트 후에는 전체 대상을 확인하세요.
JSON 출력은 두 칸 들여쓰기를 적용하고 끝에 줄바꿈을 추가해 직렬화합니다. 공백이나 주석이 바이트 단위까지 그대로 보존되지는 않습니다. 주석이 있는 원본 파일은 JSONC를 참고하세요. 다시 작성된 파일을 원본과 동등한 것으로 간주하기 전에 해당 파일을 사용하는 시스템의 요구 사항도 확인하세요.
번역 워크플로는 지원되는 자리표시자와 ICU 구조를 검사하며, 변경되거나 누락된 인수도 확인합니다. 보고된 경고나 실패를 살펴본 뒤, 애플리케이션의 값을 사용해 승인된 템플릿을 렌더링하세요. 이러한 검사만으로는 번역된 메시지가 의도한 의미를 전달하는지 평가할 수 없습니다.
대표적인 값을 사용해 애플리케이션에서 출력을 불러오세요. 보호된 경로에 의도한 원본 또는 대상 데이터가 유지되는지, 값을 대입한 뒤에도 최종 메시지가 동일한 약속을 전달하는지 확인하세요. 파싱으로 JSON 구문을 검증하고, 렌더링한 결과를 직접 읽으며 사용자에게 전달되는 메시지를 검증하세요.