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。每次修改 Locale 时 version 都会递增。

默认 Locale、optional 与 fallback

这三个属性分别决定以下内容。

• default：是否为 Space 的默认 Locale。一个 Space 只有一个默认 Locale，且只有该 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 分别存储字段值的主体数据。