本地化配置 Cluster（LocalizationConfiguration）

Cluster ID: 0x002B  |  所在 Endpoint: Endpoint 0（Root / Node 级别）

LocalizationConfiguration 用于管理设备的语言和区域设置。它让控制端（App / 语音助手）能够查询设备支持哪些语言， 并切换设备当前使用的语言区域。语言标签遵循 BCP 47 标准（如 "en-US"、"zh-CN"）。

这个 Cluster 非常简单 —— 只有 2 个属性，没有命令。 语言切换通过直接 Write（写入） ActiveLocale 属性完成。

什么时候用

用户在 App 里切换设备语言（比如把门锁的语音提示从英文改成中文）时， 就是向这个 Cluster 写入新的 ActiveLocale 值。 也可以在配网完成后自动将设备语言设置为与手机系统语言一致。

属性总览

LocalizationConfiguration 只有两个属性，都是必须支持的。点击属性 ID 可跳转到详细说明。

ID 名称 类型 读写 说明
0x00 ActiveLocale string 读写 当前生效的语言区域（BCP 47 标签）
0x01 SupportedLocales list<string> 只读 设备支持的所有语言区域列表

ActiveLocale（当前语言区域）

设备当前生效的语言区域标签，格式为 BCP 47（如 "en-US"、"zh-CN"）。 写入一个新值即可切换设备语言，但写入的值必须在 SupportedLocales 列表中， 否则设备会返回 CONSTRAINT_ERROR。

BCP 47 标签格式

BCP 47 语言标签由语言代码和可选的区域代码组成，中间用连字符连接。常见示例：

  • en-US — 英语（美国）
  • zh-CN — 简体中文（中国大陆）
  • zh-TW — 繁体中文（台湾）
  • ja-JP — 日语（日本）
  • de-DE — 德语（德国）

写入示例（将设备切换为简体中文）：

{
  "writeRequests": [{
    "attributePath": {
      "endpointId": 0,
      "clusterId": "0x002B",
      "attributeId": "0x00"        // ActiveLocale
    },
    "attributeValue": "zh-CN"      // 切换为简体中文
  }]
}

↑ 返回属性列表

SupportedLocales（支持的语言列表）

只读属性，返回设备支持的所有语言区域标签列表。列表内容由设备固件决定，App 端无法修改。 在切换语言之前，应先读取这个属性确认设备支持目标语言。

注意

不同设备的支持列表差异很大。低成本设备可能只支持 ["en-US"] 一种语言， 而高端设备可能支持十几种。App 切换语言前务必检查此列表，避免写入不支持的值导致错误。

↑ 返回属性列表

命令（Commands）

LocalizationConfiguration Cluster 没有定义任何命令。 所有操作都通过直接读写属性完成 —— 读取 SupportedLocales 查看支持的语言， 写入 ActiveLocale 切换语言。这是 Matter 中最简单的交互模式之一。

示例数据

读取一个智能门锁设备的 LocalizationConfiguration Cluster 属性：

{
  // --- 属性 ---
  "0x0": "en-US",           // ActiveLocale = 当前语言区域
  "0x1": [                  // SupportedLocales = 设备支持的语言列表
    "en-US",
    "zh-CN",
    "zh-TW",
    "ja-JP",
    "ko-KR",
    "de-DE",
    "fr-FR"
  ]
}

实际场景

场景一：配网后自动设置设备语言

设备配网完成后，App 自动将设备语言与手机系统语言对齐，避免用户手动设置：

  1. 获取手机系统语言（如 "zh-CN"）
  2. 读取设备的 SupportedLocales 属性，得到支持列表
  3. 检查系统语言是否在支持列表中：
    • 精确匹配优先（"zh-CN"）
    • 无精确匹配则尝试语言前缀匹配（"zh" 开头的任意项）
    • 都没有则保持设备默认语言，不做修改
  4. 匹配成功后，Write 写入 ActiveLocale 完成切换
场景二：App 语言设置界面

在设备详情页提供「语言设置」选项，让用户手动选择设备语言：

  1. 进入设备语言设置页，读取 SupportedLocales 渲染可选列表
  2. 读取 ActiveLocale 标记当前选中项
  3. 用户选择新语言后，Write 写入 ActiveLocale
  4. 写入成功后刷新 UI；若返回 CONSTRAINT_ERROR，提示用户该语言不受支持

建议将 BCP 47 标签转换为用户可读的语言名称显示（如 "zh-CN" 显示为「简体中文」）， 避免直接展示原始标签。

开发建议

LocalizationConfiguration 影响的是设备本身的语言行为（如语音提示、屏幕显示文字）， 不影响 App 端的 UI 语言。切换后设备可能需要几秒钟才能完成内部语言资源的加载， 期间设备行为可能短暂保持旧语言。