# Locale

A *Locale* is a language setting that a *Space* supports. Each *Locale* has a language code (`code`, e.g. `ko-KR`), whether it is the *Space*'s default *Locale* (`default`), whether this *Locale* may be left empty when filling a required (`required`) field (`optional`), and the *Locale* to look up instead when a value is missing (`fallbackCode`). The CDA (Content Delivery API) delivers this list read-only. Creating or editing a *Locale* is the responsibility of [CMA Locale](/api/reference/cma/locale.md).

The `locale` query parameter value you pass when reading *Content* or *Media* is exactly this *Locale*'s `code`. To find out which codes you may use, first read the list of *Locale*s a *Space* supports through this endpoint, then use the `code` values it contains.

## Resource structure {#resource-structure}

The following is how CDA delivers one *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:

- `sys.code`: The language code of this *Locale*. You put this value into the `locale` parameter when reading *Content* or *Media*.
- `sys.default`: Whether this *Locale* is the *Space*'s default *Locale*. A *Space* has one default *Locale*, and `default` is `true` only on that *Locale*.
- `sys.name`: The human-readable name (e.g. `"English (United States)"`). In query parameters you use `code`, not this name.
- `optional`: Whether you may leave this *Locale* empty when filling a `required` field. Both *Locale*s in the list example below have `optional` set to `false`.
- `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 on the *Locale* 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)"`). |
| `code` | string | Language code (e.g. `ko-KR`). Becomes the `locale` value when reading *Content* or *Media*. |
| `default` | boolean | Whether it is the *Space*'s default *Locale*. Only one in a *Space* is `true`. |
| `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 each time the resource is updated. |

Because a *Locale* is a *Space* setting resource rather than a published snapshot, the `revision`, `status`, and `publish` found in a *Content*'s `sys` are not carried.

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. |

## Behavior notes {#behavior-notes}

A *Locale* whose `default` is `true` must be filled when creating *Content*, and when reading *Content* or *Media* you resolve values by specifying `locale` as that `code`. If `fallbackCode` is set, then when the requested *Locale* has no value, the lookup moves to the *Locale* that `fallbackCode` points to (and if that *Locale* also has a `fallbackCode`, the chain continues). A *Locale* with no `fallbackCode` returns `null` as is when a value is missing. The default *Locale*, fallback, and required-fill rules are covered in [Localization (concept)](/getting-started/core-concepts/content/localization.md).

## API {#api}

The base URL for the endpoint below is `https://cda.weegloo.com/v1`, and a Bearer token that authenticates against CDA is required in the `Authorization` header. Because the *Locale* list is the language setting itself, unlike reading *Content* or *Media* it does not take a `locale` query parameter.

```api-endpoint
{
  "title": "List Locales",
  "method": "GET",
  "path": "/spaces/{spaceId}/locales",
  "description": "Reads the list of Locales a Space supports, page by page. Because a Locale is a language setting, it does not take a locale query parameter. The code it contains becomes the locale value when reading Content or Media.",
  "responseStatus": 200,
  "baseUrl": "https://cda.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 (CDA authentication; usually a DeliveryAccessToken)" }
  },
  "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,
        "fallbackCode": "en-US"
      }
    ],
    "links": { "self": "/v1/spaces/tcq4V2Xb/locales" }
  }
}
```

## Related documents {#related-documents}

- [CDA overview](/api/reference/cda.md): CDA as a whole and its common delivery behavior.
- [CDA Content](/api/reference/cda/content.md): Receiving Content delivered with values resolved by locale.
- [Localization (concept)](/getting-started/core-concepts/content/localization.md): The default Locale, fallback, and required-fill rules.