Locale

Locale은 Space가 지원하는 언어 설정입니다. 각 Locale은 언어 코드(code, 예: ko-KR·en-US)를 가지며, Content나 Media의 필드 값은 이 Locale별로 따로 저장됩니다. 한국어 값과 영어 값을 같은 필드에 나란히 담아 두고, 조회할 때 원하는 언어의 값을 골라 받는 식입니다.

이 페이지는 Locale을 만들고 고치는 CMA(Content Management API) 관리 작업을 다룹니다. 발행된 Locale 목록을 방문자에게 읽기 전용으로 전달하는 쪽은 CDA Locale입니다.

리소스 구조

다음은 데모 Space의 기본 Locale 한 건("English (United States)")입니다. sys(시스템 속성)와 함께, Locale의 본문 속성인 optional을 가집니다.

{
  "sys": {
    "id": "4PXRRUpIqJ1sdcqujzO7lYJD1sReNG",
    "type": "Locale",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "name": "English (United States)",
    "default": true,
    "code": "en-US",
    "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-06-17T10:43:31.960Z",
    "updatedAt": "2026-06-17T10:43:31.960Z",
    "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "version": 1
  },
  "optional": false
}

주요 키:

• code: 이 Locale의 언어 코드입니다(예: en-US). Content·Media 조회의 locale 파라미터에 이 값을 넣어 그 언어의 값을 받습니다. 생성 시 지정하며, 이후에는 바꿀 수 없습니다.
• default: 이 Locale이 Space의 기본 Locale인지 여부입니다. Space에는 기본 Locale이 하나 있고, 그 Locale에서만 default가 true입니다.
• optional: 필수(required) 필드를 채울 때 이 Locale을 비워 둘 수 있는지 여부입니다. 위 예시는 false라서 비워 둘 수 없습니다.
• fallbackCode: 값이 없을 때 대신 찾아볼 다른 Locale의 code입니다(옵션). 설정했을 때만 응답에 나타납니다. 위 예시에는 설정돼 있지 않아 키가 보이지 않습니다.

시스템 속성 (sys)와 본문

space·createdBy·updatedBy는 Refer 모양({ "sys": { "id", "type": "Refer", "targetType" } })으로 들어갑니다.

본문 속성:

name은 code에서 자동으로 산출됩니다(예: ja-JP → "Japanese (Japan)"). 그래서 생성·수정 본문에는 name을 넣지 않습니다.

Locale은 발행 개념이 없는 설정 리소스입니다. 그래서 Content·Media와 달리 sys에 publish·archive·status가 없고, version만 가집니다. version은 Locale을 수정할 때마다 오릅니다.

기본 Locale·optional·fallback

세 속성은 각각 다음을 정합니다.

• default: Space의 기본 Locale인지 여부입니다. 한 Space에 기본은 하나뿐이고, 그 Locale에서만 default가 true입니다. 생성할 때는 default를 지정할 수 없습니다(새로 만든 Locale은 기본이 아닙니다). 기본을 바꾸려면 수정(PUT)에서 default를 true로 줍니다. 그러면 그 Locale이 새 기본이 되고, 기존 기본은 해제됩니다.
• optional: 필수(required) 필드를 채울 때 이 Locale을 비워 둘 수 있는지 여부입니다. optional이 false면 그 언어 값을 반드시 채워야 하고, true면 비워 둘 수 있습니다.
• fallbackCode: 값이 없을 때 대신 찾아볼 다른 Locale의 code입니다. 요청한 Locale에 값이 없으면 fallbackCode가 가리키는 Locale로 넘어가 값을 찾습니다. 넘어간 Locale에도 fallbackCode가 있으면 계속 이어지는 체인이 됩니다. 설정하지 않으면 키 자체가 응답에 없습니다.

기본 Locale·필수 채움·fallback의 상세 동작은 다국어 (개념)에서 다룹니다.

API

아래 모든 엔드포인트의 기준 URL은 https://cma.weegloo.com/v1이며, Authorization 헤더에 CMA를 인증하는 Bearer 토큰이 필요합니다. 수정·부분 수정에는 낙관적 동시성 제어를 위해 X-Weegloo-Version 헤더(현재 리소스의 sys.version)를 함께 보내야 합니다. 생성과 삭제에는 이 헤더가 없습니다.

관련 문서

• CDA Locale: 발행된 Locale 목록을 방문자에게 전달(읽기).
• 다국어 (개념): 기본 Locale·optional·fallbackCode 규칙.
• Content: 필드 값을 Locale별로 저장하는 본문 데이터.