# Locale A *Locale* is a language setting that a *Space* supports. Each *Locale* has a language code (`code`, e.g. `ko-KR`, `en-US`), and field values of *Content* or *Media* are stored separately per *Locale*. You keep the Korean value and the English value side by side in the same field, and when reading you pick out the value in the language you want. This page covers the CMA (Content Management API) management operations for creating and editing a *Locale*. Delivering the list of published *Locale*s read-only to visitors is the responsibility of [CDA Locale](/api/reference/cda/locale.md). ## Resource structure {#resource-structure} The following is one default *Locale* from the demo *Space* ("English (United States)"). Along with `sys` (system properties), it has `optional`, the *Locale*'s body property. ```json { "sys": { "id": "3trmXRM3RqbgSnifyg7PAlm5PVgE8o", "type": "Locale", "space": { "sys": { "id": "tcq4V2Xb", "type": "Refer", "targetType": "Space" } }, "name": "English (United States)", "default": true, "code": "en-US", "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }, "createdAt": "2026-06-17T16:21:10.310Z", "updatedAt": "2026-06-17T16:21:10.310Z", "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }, "version": 1 }, "optional": false } ``` Key properties: - `code`: The language code of this *Locale* (e.g. `en-US`). You put this value into the `locale` parameter when reading *Content* or *Media* to receive that language's value. It is specified on create and cannot be changed afterward. - `default`: Whether this *Locale* is the *Space*'s default *Locale*. A *Space* has one default *Locale*, and `default` is `true` only on that *Locale*. - `optional`: Whether you may leave this *Locale* empty when filling a `required` field. The example above is `false`, so it cannot be left empty. - `fallbackCode`: The `code` of another *Locale* to look up instead when a value is missing (optional). It appears in the response only when it is set. It is not set in the example above, so the key is not shown. ## System properties (sys) and body {#system-properties-sys-and-body} `space`, `createdBy`, and `updatedBy` come in the `Refer` shape (`{ "sys": { "id", "type": "Refer", "targetType" } }`). | Property | Type | Description | |---|---|---| | `id` | string | Unique resource identifier. | | `type` | string | Resource kind. For a *Locale* this is always `"Locale"`. | | `space` | Refer<Space> | The *Space* this *Locale* belongs to. | | `name` | string | Human-readable name (e.g. `"English (United States)"`). It is generated automatically from `code`. | | `default` | boolean | Whether it is the *Space*'s default *Locale*. Only one in a *Space* is `true`. | | `code` | string | Language code (e.g. `ko-KR`). Becomes the `locale` value when reading *Content* or *Media*. | | `createdBy` | Refer<User> | The user who created it. | | `createdAt` | string (date-time) | Creation time. | | `updatedBy` | Refer<User> | The user who last updated it. | | `updatedAt` | string (date-time) | Last update time. | | `version` | integer | The current version. It increases by 1 each time the resource is updated. | Body properties: | Property | Type | Description | |---|---|---| | `optional` | boolean | Whether you may leave this *Locale* empty when filling a `required` field. The default *Locale* is usually `false` (must be filled). | | `fallbackCode` | string | The `code` of the *Locale* to look up instead when a value is missing (optional, chainable). If it is not set, the key itself is absent from the response. | `name` is derived automatically from `code` (e.g. `ja-JP` → `"Japanese (Japan)"`). For that reason you do not include `name` in the create or update body. A *Locale* is a settings resource with no publishing concept. So unlike *Content* and *Media*, its `sys` has no `publish`, `archive`, or `status`, only `version`. The `version` increases each time you update the *Locale*. ## Default Locale, optional, and fallback {#default-locale-optional-and-fallback} These three properties each determine the following. - `default`: Whether this *Locale* is the *Space*'s default *Locale*. A *Space* has only one default, and `default` is `true` only on that *Locale*. You cannot specify `default` when creating (a newly created *Locale* is not the default). To change the default, set `default` to `true` in an update (PUT). That *Locale* then becomes the new default, and the previous default is unset. - `optional`: Whether you may leave this *Locale* empty when filling a `required` field. If `optional` is `false`, that language's value must be filled; if `true`, it may be left empty. - `fallbackCode`: The `code` of another *Locale* to look up instead when a value is missing. If the requested *Locale* has no value, the lookup moves to the *Locale* that `fallbackCode` points to. If that *Locale* also has a `fallbackCode`, the chain continues. If it is not set, the key itself is absent from the response. The detailed behavior of the default *Locale*, required-fill, and fallback is covered in [Localization (concept)](/getting-started/core-concepts/content/localization.md). ## API {#api} The base URL for all endpoints below is `https://cma.weegloo.com/v1`, and a Bearer token that authenticates against CMA is required in the `Authorization` header. Update and partial update must also send the `X-Weegloo-Version` header (the current resource's `sys.version`) for optimistic concurrency control. Create and delete do not have this header. ```api-endpoint { "title": "List Locales", "method": "GET", "path": "/spaces/{spaceId}/locales", "description": "Reads the list of Locales a Space supports, page by page. The code it contains becomes the locale value when reading Content or Media.", "responseStatus": 200, "baseUrl": "https://cma.weegloo.com/v1", "pathParameterSchema": { "spaceId": { "type": "string", "description": "The sys.id of the Space", "required": true } }, "queryParameterSchema": { "limit": { "type": "integer", "description": "Number of items to return per page (1-100)", "default": 15 }, "skip": { "type": "integer", "description": "Number of items to skip", "default": 0 }, "next": { "type": "string", "description": "Next page cursor (the value obtained from links.next in the previous response)" }, "prev": { "type": "string", "description": "Previous page cursor (the value obtained from links.prev in the previous response)" }, "order": { "type": "string", "description": "Sort criteria. Comma-separated for multi-level sorting (e.g. sys.createdAt,sys.id)", "default": "sys.createdAt,sys.id" }, "include": { "type": "integer", "description": "Related-resource inclusion level. 0=default, 1=related resources, 2=nested relations, 3=full", "default": 0 }, "select": { "type": "string", "description": "Fields to include (sys.id,sys.code) or exclude (-sys.id). Do not mix include and exclude." } }, "additionalQueryParams": true, "requestHeaderSchema": { "Authorization": { "type": "string", "description": "Bearer token (CMA authentication)" } }, "responseExample": { "sys": { "type": "TotalPageResponse" }, "limit": 15, "totalCount": 2, "items": [ { "sys": { "id": "3trmXRM3RqbgSnifyg7PAlm5PVgE8o", "type": "Locale", "space": { "sys": { "id": "tcq4V2Xb", "type": "Refer", "targetType": "Space" } }, "name": "English (United States)", "default": true, "code": "en-US", "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }, "createdAt": "2026-06-17T16:21:10.310Z", "updatedAt": "2026-06-17T16:21:10.310Z", "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }, "version": 1 }, "optional": false }, { "sys": { "id": "3trmXRM3RqbgSnifyg7PMyuzbcVRho", "type": "Locale", "space": { "sys": { "id": "tcq4V2Xb", "type": "Refer", "targetType": "Space" } }, "name": "Korean (South Korea)", "default": false, "code": "ko-KR", "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }, "createdAt": "2026-06-18T03:02:40.667Z", "updatedAt": "2026-06-18T03:02:40.667Z", "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }, "version": 1 }, "optional": false } ], "links": { "self": "/v1/spaces/tcq4V2Xb/locales" } } } ``` ```api-endpoint { "title": "Read a single Locale", "method": "GET", "path": "/spaces/{spaceId}/locales/{localeId}", "description": "Reads one Locale by sys.id.", "responseStatus": 200, "baseUrl": "https://cma.weegloo.com/v1", "pathParameterSchema": { "spaceId": { "type": "string", "description": "The sys.id of the Space", "required": true }, "localeId": { "type": "string", "description": "The sys.id of the Locale", "required": true } }, "queryParameterSchema": { "include": { "type": "integer", "description": "Related-resource inclusion level. 0=default, 1=related resources, 2=nested relations, 3=full", "default": 0 } }, "requestHeaderSchema": { "Authorization": { "type": "string", "description": "Bearer token (CMA authentication)" } }, "responseExample": { "sys": { "id": "3trmXRM3RqbgSnifyg7PAlm5PVgE8o", "type": "Locale", "space": { "sys": { "id": "tcq4V2Xb", "type": "Refer", "targetType": "Space" } }, "name": "English (United States)", "default": true, "code": "en-US", "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }, "createdAt": "2026-06-17T16:21:10.310Z", "updatedAt": "2026-06-17T16:21:10.310Z", "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }, "version": 1 }, "optional": false } } ``` ```api-endpoint { "title": "Create Locale", "method": "POST", "path": "/spaces/{spaceId}/locales", "description": "Creates a new Locale in a Space. The body holds code and optional, and fallbackCode is optional. name is generated automatically from code, so you do not send it. A newly created Locale is not the default, so default starts as false and cannot be specified in the body.", "responseStatus": 201, "baseUrl": "https://cma.weegloo.com/v1", "pathParameterSchema": { "spaceId": { "type": "string", "description": "The sys.id of the Space", "required": true } }, "requestHeaderSchema": { "Authorization": { "type": "string", "description": "Bearer token (CMA authentication)" } }, "requestBodySchema": { "type": "object", "required": ["code", "optional"], "properties": { "code": { "type": "string", "description": "Language code (e.g. ja-JP). It cannot be changed after creation." }, "optional": { "type": "boolean", "description": "Whether you may leave this Locale empty when filling required fields" }, "fallbackCode": { "type": "string", "description": "The code of another Locale to look up instead when a value is missing (optional)" } }, "example": { "code": "ja-JP", "optional": true } }, "responseExample": { "sys": { "id": "3trmXRM3RqbgSnifyg7PAjaJPex01", "type": "Locale", "space": { "sys": { "id": "tcq4V2Xb", "type": "Refer", "targetType": "Space" } }, "name": "Japanese (Japan)", "default": false, "code": "ja-JP", "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }, "createdAt": "2026-06-18T11:00:00.000Z", "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }, "updatedAt": "2026-06-18T11:00:00.000Z", "version": 1 }, "optional": true } } ``` ```api-endpoint { "title": "Update Locale", "method": "PUT", "path": "/spaces/{spaceId}/locales/{localeId}", "description": "Updates the Locale's default, optional, and fallbackCode. code cannot be changed, so it is not in the body. Setting default to true makes this Locale the Space's default and unsets the previous default. You must carry the current sys.version in the X-Weegloo-Version header.", "responseStatus": 200, "baseUrl": "https://cma.weegloo.com/v1", "pathParameterSchema": { "spaceId": { "type": "string", "description": "The sys.id of the Space", "required": true }, "localeId": { "type": "string", "description": "The sys.id of the Locale", "required": true } }, "requestHeaderSchema": { "Authorization": { "type": "string", "description": "Bearer token (CMA authentication)" }, "X-Weegloo-Version": { "type": "integer", "description": "The current resource's sys.version (optimistic concurrency control)" } }, "requestBodySchema": { "type": "object", "required": ["default", "optional"], "properties": { "default": { "type": "boolean", "description": "Whether to make this Locale the Space's default. If true, the previous default is unset." }, "optional": { "type": "boolean", "description": "Whether you may leave this Locale empty when filling required fields" }, "fallbackCode": { "type": "string", "description": "The code of another Locale to look up instead when a value is missing (optional)" } }, "example": { "fallbackCode": "ko-KR", "optional": true, "default": false } }, "responseExample": { "sys": { "id": "3trmXRM3RqbgSnifyg7PAjaJPex01", "type": "Locale", "space": { "sys": { "id": "tcq4V2Xb", "type": "Refer", "targetType": "Space" } }, "name": "Japanese (Japan)", "default": false, "code": "ja-JP", "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }, "createdAt": "2026-06-18T11:00:00.000Z", "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }, "updatedAt": "2026-06-18T11:00:12.000Z", "version": 2 }, "fallbackCode": "ko-KR", "optional": true } } ``` ```api-endpoint { "title": "Partially update Locale (JSON Patch)", "method": "PATCH", "path": "/spaces/{spaceId}/locales/{localeId}", "description": "Updates only part of a Locale (default, optional, fallbackCode) using RFC 6902 JSON Patch. The request Content-Type header must be application/json-patch+json. You must carry the current sys.version in the X-Weegloo-Version header.", "responseStatus": 200, "baseUrl": "https://cma.weegloo.com/v1", "requestContentType": "application/json-patch+json", "pathParameterSchema": { "spaceId": { "type": "string", "description": "The sys.id of the Space", "required": true }, "localeId": { "type": "string", "description": "The sys.id of the Locale", "required": true } }, "requestHeaderSchema": { "Authorization": { "type": "string", "description": "Bearer token (CMA authentication)" }, "Content-Type": { "type": "string", "description": "application/json-patch+json (RFC 6902 JSON Patch)" }, "X-Weegloo-Version": { "type": "integer", "description": "The current resource's sys.version (optimistic concurrency control)" } }, "requestBodySchema": { "type": "array", "description": "An array of RFC 6902 JSON Patch operations (op / path / value / from). path is an RFC 6901 JSON Pointer.", "items": { "type": "object", "required": ["op", "path"], "properties": { "op": { "type": "string", "enum": ["add", "remove", "replace", "move", "copy", "test"], "description": "Operation kind" }, "path": { "type": "string", "description": "Target location (JSON Pointer). Example: /optional" }, "value": { "description": "The value used by add/replace/test" }, "from": { "type": "string", "description": "The source location for move/copy" } } }, "example": [ { "op": "replace", "path": "/optional", "value": false } ] }, "responseExample": { "sys": { "id": "3trmXRM3RqbgSnifyg7PAjaJPex01", "type": "Locale", "space": { "sys": { "id": "tcq4V2Xb", "type": "Refer", "targetType": "Space" } }, "name": "Japanese (Japan)", "default": false, "code": "ja-JP", "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }, "createdAt": "2026-06-18T11:00:00.000Z", "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }, "updatedAt": "2026-06-18T11:00:12.000Z", "version": 3 }, "fallbackCode": "ko-KR", "optional": false } } ``` ```api-endpoint { "title": "Delete Locale", "method": "DELETE", "path": "/spaces/{spaceId}/locales/{localeId}", "description": "Deletes a Locale. On success it responds with 204 No Content and no response body.", "responseStatus": 204, "baseUrl": "https://cma.weegloo.com/v1", "pathParameterSchema": { "spaceId": { "type": "string", "description": "The sys.id of the Space", "required": true }, "localeId": { "type": "string", "description": "The sys.id of the Locale", "required": true } }, "requestHeaderSchema": { "Authorization": { "type": "string", "description": "Bearer token (CMA authentication)" } } } ``` ## Related documents {#related-documents} - [CDA Locale](/api/reference/cda/locale.md): Delivering the list of published *Locale*s to visitors (read). - [Localization (concept)](/getting-started/core-concepts/content/localization.md): The default *Locale*, `optional`, and `fallbackCode` rules. - [Content](/api/reference/cma/content.md): The body data that stores field values per *Locale*.