Streamdeck Profiles Localization

Stream Deck Plugin — Profiles, Localization, Touch-Strip Layouts

Prerequisite: streamdeck-manifest (the manifest fields for Profiles, Encoder.layout, and localized strings live there) and streamdeck-general (file layout).

Purpose

Three loosely-coupled concerns, grouped because none of them is big enough to be its own skill:

1. Bundled profiles — ship a curated layout of buttons the user can install with one click.
2. Localization (i18n) — translate action names, tooltips, and PI strings into supported languages.
3. Touch-strip layouts — custom JSON designs for the Stream Deck + touch strip beyond the six built-in templates.

PART 1 — Bundled Profiles

A profile is a saved arrangement of buttons + actions + plugin configuration for a particular Stream Deck device. Bundling one with your plugin lets the user opt in to a curated starting point.

1.1 Create the profile asset

In the Stream Deck desktop app:

1. Set up the layout exactly as you want it on a real device.
2. Stream Deck Preferences → Profiles → Export.
3. Save as <my-profile>.streamDeckProfile.

Copy the resulting file into your plugin folder:

<UUID>.sdPlugin/
└── profiles/
    └── default-layout.streamDeckProfile

1.2 Declare it in the manifest

{
  "Profiles": [
    {
      "Name":                       "profiles/default-layout",   // path, NO .streamDeckProfile extension
      "DeviceType":                 0,                           // 0 = Stream Deck MK.2, see device type table
      "Readonly":                   false,
      "AutoInstall":                true,
      "DontAutoSwitchWhenInstalled":false
    }
  ]
}

1.3 Switch to a bundled profile from your plugin

import streamDeck, { action, SingletonAction,
  type KeyDownEvent,
} from "@elgato/streamdeck";

@action({ UUID: "com.yourhandle.streaming.show-overlay" })
export class ShowOverlay extends SingletonAction {
  override async onKeyDown(ev: KeyDownEvent): Promise<void> {
    await streamDeck.profiles.switchToProfile(
      ev.action.device.id,
      "default-layout",                                  // === manifest Name basename
      0,                                                 // optional: page index inside the profile
    );
  }
}

1.4 Rules and limits

PART 2 — Localization (i18n)

Stream Deck ships with localized versions in:

If the user has Stream Deck set to one of those languages, your plugin can serve translated strings.

2.1 Manifest string overrides (the easy stuff)

Ship language files next to the manifest:

<UUID>.sdPlugin/
├── manifest.json
├── en.json
├── de.json
└── ja.json

Each language file mirrors the manifest fields you want translated, keyed by the action UUID for action strings:

// de.json
{
  "Name":        "Hallo Welt",
  "Description": "Demonstriert das SDK.",
  "com.yourhandle.hello-world.greet": {
    "Name":    "Grüßen",
    "Tooltip": "Sagt Hallo.",
    "States": [
      { "Name": "Aus" },
      { "Name": "An"  }
    ]
  },
  "Localization": {
    "Save":  "Speichern",
    "Reset": "Zurücksetzen"
  }
}

If a language file is missing OR a key is missing inside it, Stream Deck falls back to the value in manifest.json.

2.2 Translating dynamic strings — streamDeck.i18n

import streamDeck from "@elgato/streamdeck";

const label = streamDeck.i18n.translate("Save");
// Returns "Speichern" if user is on German, "Save" otherwise.

// With explicit language override (rarely needed)
const labelDe = streamDeck.i18n.translate("Save", "de");

Lookup chain: <active-language>.json → en.json → the key itself.

sdpi-components have their own localization mechanism (the data-localize attribute and a translations file referenced in the HTML). Consult the sdpi-components docs if you go deep on PI i18n; for most plugins the auto-translated manifest fields are enough.

2.3 What to translate vs. what to leave

PART 3 — Touch-Strip Layouts (Stream Deck +)

The touch strip on Stream Deck + is divided into four 200×100 px canvases, one per dial action. The SDK gives you six built-in templates and a JSON schema for custom layouts.

3.1 Built-in layouts — pick one in the manifest

"Encoder": { "layout": "$B1" }

Update from your action with setFeedback:

await ev.action.setFeedback({
  title:     "Volume",
  value:     "75%",
  indicator: { value: 75 },
});

Built-in keys: title, value, value2, value3, indicator, icon. The exact set depends on the chosen layout.

3.2 Custom layouts

When the built-ins don't cut it, author a JSON layout file alongside the manifest:

<UUID>.sdPlugin/
└── layouts/
    └── eq-meter.json

Set it as either the default in the manifest:

"Encoder": { "layout": "layouts/eq-meter.json" }

Or programmatically at runtime:

await ev.action.setFeedbackLayout("layouts/eq-meter.json");

3.3 Custom layout JSON shape

{
  "$schema": "https://schemas.elgato.com/streamdeck/plugins/layout.json",
  "id":      "eq-meter",
  "items": [
    {
      "key":     "title",
      "type":    "text",
      "rect":    [0, 0, 200, 16],
      "alignment":  "center",
      "color":      "#ffffff",
      "font":       { "size": 12, "weight": 600 }
    },
    {
      "key":     "bass",
      "type":    "bar",
      "rect":    [0, 24, 200, 16],
      "subtype": 1,
      "value":   0,
      "range":   { "min": 0, "max": 100 },
      "bar_fill_c":   "#26d07c",
      "bar_border_c": "#202020",
      "border_w":     1
    },
    {
      "key":     "treble",
      "type":    "bar",
      "rect":    [0, 48, 200, 16],
      "subtype": 1,
      "value":   0,
      "range":   { "min": 0, "max": 100 },
      "bar_fill_c":   "#3aa0ff"
    },
    {
      "key":     "vu",
      "type":    "gbar",
      "rect":    [0, 72, 200, 28],
      "subtype": 2,
      "value":   0,
      "range":   { "min": 0, "max": 100 },
      "bar_fill_c": "#ffcc00"
    }
  ]
}

3.4 Item type reference

3.5 Updating from your action

await ev.action.setFeedback({
  title:  "EQ",
  bass:   { value: 65 },
  treble: { value: 40 },
  vu:     { value: 85, bar_fill_c: "#ff0000" },          // mutate any item key
});

Pass the value directly when you only need to change the value, or pass an object to update multiple item fields.

3.6 Touch-strip layout rules

See Also

• Profiles guide: https://docs.elgato.com/streamdeck/sdk/guides/profiles
• Localization (i18n) guide: https://docs.elgato.com/streamdeck/sdk/guides/i18n
• Touch Strip Layout reference: https://docs.elgato.com/streamdeck/sdk/references/touch-strip-layout
• Layout JSON schema: https://schemas.elgato.com/streamdeck/plugins/layout.json
• Sibling skills: streamdeck-manifest (Profiles/Encoder fields), streamdeck-actions (setFeedback, setFeedbackLayout)