国际化（i18n）

插件可以为名称、描述、灯效分类、参数标签、参数分组、下拉选项和通知等用户可见文本提供翻译。

面向插件商城的插件应把可翻译元数据放在 manifest.json 中。这样 Skydimo 可以在不运行插件代码、不读取额外翻译文件的情况下预览、索引和校验插件元数据。

Manifest 本地化

在元数据字段中写 i18n key，然后在顶层 locales 对象中声明各语言词典：

manifest.json

{
  "id": "rainbow",
  "version": "1.0.0",
  "name": "meta.name",
  "publisher": "Your Name",
  "description": "meta.description",
  "type": "effect",
  "language": "lua",
  "entry": "main.lua",
  "category": "meta.category",
  "params": [
    {
      "key": "speed",
      "label": "params.speed",
      "group": "params.groups.animation",
      "kind": "slider",
      "default": 2.5,
      "min": 0,
      "max": 5,
      "step": 0.1
    },
    {
      "key": "preset",
      "label": "params.preset",
      "kind": "select",
      "default": 0,
      "options": [
        { "label": "params.presets.custom", "value": 0 },
        { "label": "params.presets.rainbow", "value": 1 }
      ]
    }
  ],
  "locales": {
    "en-US": {
      "meta": {
        "name": "Rainbow",
        "description": "Flowing rainbow animation across all LEDs",
        "category": "Animation"
      },
      "params": {
        "speed": "Speed",
        "preset": "Preset",
        "presets": {
          "custom": "Custom",
          "rainbow": "Rainbow"
        },
        "groups": {
          "animation": "Animation"
        }
      }
    },
    "zh-CN": {
      "meta": {
        "name": "彩虹",
        "description": "流动的彩虹动画效果",
        "category": "动画"
      },
      "params": {
        "speed": "速度",
        "preset": "预设",
        "presets": {
          "custom": "自定义",
          "rainbow": "彩虹"
        },
        "groups": {
          "animation": "动画"
        }
      }
    }
  }
}

使用 i18n 键

在 manifest.json 中，使用引用本地化词典条目的键，代替字面字符串：

manifest.json

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

像 meta.name 这样的键，既可以从嵌套词典解析，也可以从扁平词典解析：

嵌套词典

{
  "meta": {
    "name": "Rainbow",
    "description": "Flowing rainbow animation across all LEDs"
  }
}

扁平词典

{
  "meta.name": "Rainbow",
  "meta.description": "Flowing rainbow animation across all LEDs"
}

推荐使用嵌套词典，因为插件元数据增长后更易维护。

如果某个键找不到翻译，Skydimo 会显示原始字符串。因此可以混合使用翻译元数据和字面值：

manifest.json

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

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

推荐本地化的元数据字段

对用户可见的元数据建议使用 i18n key：

范围	字段
插件基础元数据	name、description
灯效元数据	category
灯效参数	label、group
下拉选项	options[].label
扩展通知	以本地化文本对象或 manifest key 传入的 title、description

不要本地化标识符或运行字段，例如 id、type、language、entry、permissions、参数 key、下拉选项 value。

支持的语言

Skydimo 目前支持：

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

在 locales 中请使用 en-US、zh-CN 这样的标准 locale 代码作为键。

LocalizedText 格式（API）

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

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

客户端应显示 byLocale 中最匹配用户语言的条目；如果没有匹配项，则显示 raw。