How the widget resolves its language and skin

The widget you embed has two layers: the shell (the Caputchin chrome, its checkbox or brand strip, its wording and colors) and, when you use a game, the game inside it. Each has a language and a skin, and the widget resolves both on the server when it loads. This page explains how the shell resolves, and how it lines up with the game so the two never clash.

For customizing a game's own language, skin, and configuration, see game customization. This page is about the shell.

What the shell ships

The shell is fully self-contained. It bundles its interface strings in every official language and both a light and a dark palette, so it always has something correct to render even with no customization and no network. Replacing those bundled strings, colors, or links is white-labeling, an Apex-tier feature; the resolution below is the same whether or not you have overrides.

How the shell picks a language

When the widget loads it decides which language to ask the server for, in this order:

The widget's locale attribute, if the page set one (an explicit choice).
Otherwise, the visitor's browser language.

The server then resolves that against the shell's languages (your overrides first, then the bundled set): an exact match, then the base language, then the shell's default, then its first language. So the shell always renders real wording.

How the shell picks a skin

Same shape for the skin:

The widget's skin attribute, if the page set one: light, dark, or a preset name.
Otherwise, the visitor's system preference (prefers-color-scheme).

The server resolves that to a concrete light or dark palette (your overrides first, then bundled). Each preset declares the mode it works in; a preset whose mode is any reads on either background and so is eligible for both. The shell ships a light and a dark palette out of the box, and the resolved skin always reports a concrete light or dark mode, which is what the chrome renders.

How the shell follows the game

Here is the part that ties it together. When a game is mounted, the shell does not resolve its language and skin from the visitor signal directly. Instead it follows the game: the widget resolves the game first, then uses the game's resolved language and light or dark mode as the shell's input.

So if a visitor's browser is French and the game resolves to French, the surrounding chrome renders in French too. If the game resolves to its dark skin, the chrome goes dark to match. The shell falls back to the visitor's own language and system preference only when no game is mounted (the plain checkbox widget), or when the game did not resolve a language or skin of its own.

The result is that the game and the chrome around it always agree, without you configuring the shell and the game separately to match.

Configuration

The shell also has a small configuration: the link targets in its brand strip (the home link and the legal link). Unlike language and skin, this has no visitor input; the server resolves it from your overrides or the bundled defaults. Changing those links is part of white-labeling.