Internationalization (i18n)

Plugins can provide translations for their display text (name, description, parameter labels, etc.).

Directory Structure

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

Using i18n Keys

Instead of literal strings in manifest.json, use keys that reference entries in locale files:

manifest.json

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

Locale Files

Create JSON files in the locales/ directory, named by locale code:

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": "动画"
}

How Resolution Works

1. Core reads the manifest field value (e.g. "meta.name")
2. If a matching key exists in the current locale's JSON file, the translation is used
3. If no match is found, the raw string is used as-is

This means you can mix literal strings and i18n keys:

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

Here name uses i18n lookup while publisher stays as-is.

Supported Locales

Skydimo currently supports:

Code	Language
en-US	English
zh-CN	简体中文

LocalizedText Format (API)

When Core sends localized text over the WebSocket API, it uses the LocalizedText format:

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

The frontend resolves this using resolveLocalizedText() based on the user's current language setting.