JSON 번역

JSON 객체를 컨텍스트, 힌트, 보호할 경로와 함께 제출하고 번역 결과를 다운로드하세요.

애플리케이션 메모리에 원문이 이미 있다면 로컬라이제이션 작업에 JSON 객체를 직접 전송하세요. Lingo.dev는 이를 JSON 문서로 저장하고 대상 로캘별로 결과물을 하나씩 생성합니다.

빠른 시작에서 완전한 프로그램 예제를 확인할 수 있습니다. 이 레퍼런스에서는 JSON 전용 요청 필드를 다룹니다.

인라인 문서 제출 #

X-API-Key에 API 키를 넣고 이번 제출에 사용할 고정된 Idempotency-Key을 지정해 POST /v2/organizations/:orgId/localization/jobs에서 작업을 생성하세요:

json
{
  "engineId": "YOUR_ENGINE_ID",
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "documents": [
    {
      "key": "settings.json",
      "format": {
        "type": "json",
        "options": {
          "context": "Settings dialog in a team collaboration application",
          "hints": { "$.save": ["Button that saves the edited settings"] },
          "lockedKeys": ["$.productName"]
        }
      },
      "source": {
        "content": {
          "save": "Save changes",
          "cancel": "Cancel",
          "productName": "Acme"
        }
      }
    }
  ]
}

원문은 JSON 객체여야 하며, 중첩된 객체와 배열을 포함할 수 있습니다. 말단 값이 문자열이면 번역 대상이 되며, 숫자, 불리언, 널 값은 기존 JSON 자료형을 유지합니다. 문자열 값인 식별자, 제품명, URL을 그대로 유지하려면 보호 대상으로 지정하세요.

인라인 원문에는 format.type: "json"을 사용합니다. JSONC나 다른 파일 형식이라면 파일의 바이트를 업로드하세요.

컨텍스트 추가 및 콘텐츠 선택 #

문서의 format.options 안에 JSON 옵션을 지정하세요:

옵션효과
context콘텐츠의 목적이나 독자를 설명하는 텍스트로, 비어 있으면 안 됩니다.
hintsJSONPath 쿼리를 힌트 배열에 매핑합니다. 배열과 각 힌트는 모두 비어 있으면 안 됩니다. 선택된 문자열에는 일치하는 힌트가 모두 누적됩니다. 기본값은 빈 객체입니다.
lockedKeys선택한 원문 값을 번역하지 않고 복사합니다. 기본값은 []입니다.
preservedKeys선택한 값이 이전 대상 번역에 있으면 재사용하고, 없으면 원문을 복사합니다. 기본값은 []입니다.
ignoredKeys선택한 값을 결과물에서 제거합니다. 기본값은 []입니다.
keyScope비어 있지 않은 JSONPath 쿼리 목록으로 선택한 문자열을 다시 생성합니다. 모든 대상 로캘에 이전 번역이 있어야 합니다.
termScope비어 있지 않은 원문 용어 목록과 일치하는 문자열을 다시 생성합니다. 모든 대상 로캘에 이전 번역이 있어야 합니다.
injectLocale$.meta.locale과 같은 단일 JSONPath 위치에 대상 로캘을 기록합니다. 해당 하위 트리는 번역되지 않도록 보호됩니다.

API 요청에는 JSONPath를 사용하세요. $.title은 루트 속성을, $.nav.home는 중첩된 속성을, $['nav.home']은 점이 포함된 리터럴 키를, $..productName는 깊이에 관계없이 해당 속성을 선택합니다. 객체나 배열을 선택하면 그 아래의 모든 문자열도 포함됩니다. 키 이름만으로는 유효한 API 쿼리가 되지 않습니다.

키 제어 설정은 번역 전에 처리됩니다. 무시하도록 지정한 값은 제거되고, 잠긴 원문 값은 보존된 대상 번역 값보다 우선합니다. 범위를 선택해도 이러한 제어 설정은 무시되지 않습니다. 결과물 구성과 ICU 메시지는 JSON 형식 레퍼런스를 확인하세요.

termScope은 대소문자를 구분해 원문 문자열의 부분 문자열과 일치하는지 확인합니다. 나열된 용어 중 하나라도 일치하면 해당 문자열이 선택됩니다. "cat"은 "catalog"과도 일치하지만, "login"은 "Login"과 일치하지 않습니다. 일치하는 용어만이 아니라 선택된 문자열 전체가 다시 생성됩니다. keyScope과 termScope이 모두 있으면 문자열이 두 조건을 모두 충족해야 합니다. 부분 문자열로 선택할 때 관련 없는 메시지까지 포함된다면 JSONPath로 정확한 키를 선택하세요.

작업 시작 및 결과 확인 #

작업 생성 응답의 id을 저장하세요. 이 작업이 이전 파일이나 다른 문서도 참조한다면 uploads의 모든 항목을 업로드하세요. 그런 다음 POST /v2/localization/jobs/:id/start을 호출하세요.

GET /v2/localization/jobs/:id을 읽고 각 문서의 targets를 확인하세요. status._tag: "Completed"인 대상에는 status.downloadUrl이 있습니다. 동일한 인증 정보로 해당 URL에서 다운로드하면 JSON 객체를 받을 수 있습니다. 작업 응답 자체에는 번역된 객체가 아니라 진행 상황과 산출물 주소가 담겨 있습니다.

업데이트할 때는 기존 문서 업데이트에 설명된 대로 이전 원문과 대상 번역 산출물을 제출하세요. 늦게 도착한 결과가 최신 콘텐츠를 덮어쓰지 않도록 새 원문 리비전을 작업 ID와 함께 보관하세요.