国际化（i18n）

插件可以为其显示文本（名称、描述、参数标签等）提供翻译。

目录结构

plugins/effect.my_effect/
├── manifest.json
├── main.lua
└── locales/
    ├── en-US.json
    └── zh-CN.json

使用 i18n 键

在 manifest.json 中，使用引用 locale 文件条目的键，代替字面字符串：

manifest.json

{
  "name": "meta.name",
  "description": "meta.description",
  "category": "meta.category",
  "params": [
    {
      "key": "speed",
      "label": "params.speed",
      "group": "params.groups.animation"
    }
  ]
}

Locale 文件

在 locales/ 目录下创建按 locale 代码命名的 JSON 文件：

locales/en-US.json

{
  "meta.name": "Rainbow",
  "meta.description": "Flowing rainbow animation across all LEDs",
  "meta.category": "Animation",
  "params.speed": "Speed",
  "params.preset": "Preset",
  "params.colors": "Colors",
  "params.groups.animation": "Animation"
}

locales/zh-CN.json

{
  "meta.name": "彩虹",
  "meta.description": "流动的彩虹动画效果",
  "meta.category": "动画",
  "params.speed": "速度",
  "params.preset": "预设",
  "params.colors": "颜色",
  "params.groups.animation": "动画"
}

解析流程

1. Core 读取 manifest 字段值（如 "meta.name"）
2. 如果在当前语言的 JSON 文件中找到匹配的键，则使用该翻译
3. 如果未找到匹配，则直接使用原始字符串

这意味着你可以混合使用字面字符串和 i18n 键：

{
  "name": "meta.name",
  "publisher": "Skydimo"
}

这里 name 使用 i18n 查找，而 publisher 保持原样。

支持的语言

Skydimo 目前支持：

代码	语言
en-US	English
zh-CN	简体中文

LocalizedText 格式（API）

当 Core 通过 WebSocket API 发送本地化文本时，使用 LocalizedText 格式：

{
  "raw": "Rainbow",
  "byLocale": {
    "en-US": "Rainbow",
    "zh-CN": "彩虹"
  }
}

前端根据用户当前语言设置，使用 resolveLocalizedText() 解析此格式。