Internationalization (i18n)

Plugins can provide translations for display text such as names, descriptions, effect categories, parameter labels, parameter groups, select options, and notifications.

For marketplace-ready plugins, keep translatable metadata in manifest.json. This lets Skydimo preview, index, and validate plugin metadata without running plugin code or reading extra translation files.

Manifest Locales

Use i18n keys in metadata fields, then declare the locale dictionaries in the top-level locales object:

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

Using Keys

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

manifest.json

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

Keys like meta.name can be resolved from either nested dictionaries or flat dictionaries:

nested

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

flat

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

Nested dictionaries are recommended because they are easier to maintain as metadata grows.

If no translation is available for a key, Skydimo displays the raw string. This means you can mix translated metadata and literal values:

manifest.json

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

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

Recommended Metadata Fields

Use i18n keys for user-facing metadata:

Area	Fields
Base plugin metadata	name, description
Effect metadata	category
Effect parameters	label, group
Select options	options[].label
Extension notifications	title, description values passed as localized text objects or manifest keys

Do not localize identifiers or operational fields such as id, type, language, entry, permissions, parameter key, or select option value.

Supported Locales

Skydimo currently supports:

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

Use standard locale codes such as en-US and zh-CN as keys inside locales.

LocalizedText Format (API)

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

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

Clients should display the entry in byLocale that best matches the user's language. If no matching entry exists, display raw.