TwoSky.WebComponents.LanguageBanner 1.1.0

LanguageBanner

A language selection banner web component that detects when the user's preferred language differs from the current page language. It offers to persist the current language as the user's preference or dismiss the banner for the session.

This plugin is only compatible with the Web3 Vidyano client.

Installation

After installing the NuGet package, add the following import to your app.ts:

import "../language-banner/language-banner";

Rebuild the frontend code after making this change. Then choose how the component reaches the page:

Stock Vidyano client (<vi-app>) — automatic injection

Opt a website in by adding a LanguageBanner key to its entry in App_Data/websites.json:

"CareAdmin": { "Type": 4, "Bindings": ["*/careadmin"], "LanguageBanner": "menu-footer" }

The plugin then injects the following element as the first child of <vi-app> when that website's index.html is served:

<ts-language-banner slot="menu-footer" display-mode="dropdown" theme="menu"></ts-language-banner>

vi-app forwards the menu-footer slot into the menu footer; with theme="menu" the component overlays the <vi-user> actions row, centred between the settings and sign-out buttons. Selecting a language switches the session language and reloads, after which the mismatch banner offers to use that language everywhere — the same flow as manual placement. Nothing is injected when the key is missing, when the page has no <vi-app>, or when a ts-language-banner element is already present.

Custom pages — manual placement

For a custom shell (e.g. a <ca-app> webshop) add the element yourself, in the navigation bar:

<ts-language-banner display-mode="dropdown"></ts-language-banner>

Both can be combined in one application: enable the key on the stock website only and keep manual placement in the custom page.

UserSettings "Language" field

Installing the plugin registers a CronosAdvanced.RegisterLoadUserSettingsHook handler that removes the Language attribute from Vidyano's UserSettings persistent object — but only for requests coming through a website that has the LanguageBanner key, i.e. where the dropdown replaces it. Websites without the key keep the field. To keep the field everywhere, set this in Startup:

Service.Plugins.LanguageBanner.HideUserSettingsLanguage = false;

Note: a module Advanced that overrides LoadUserSettings must call base.LoadUserSettings(args) or the handler does not run.

Display Modes

The component supports two display modes via the display-mode attribute:

Dropdown (default)

Shows a globe icon with the current language code. Clicking opens a dropdown menu with available languages.

<ts-language-banner display-mode="dropdown"></ts-language-banner>

Buttons

Shows all available languages as side-by-side buttons, with the active language highlighted.

<ts-language-banner display-mode="buttons"></ts-language-banner>

Attributes

hide-banner and persist-on-select are meant to be used together for a silent switch: the selection is saved immediately, so preferred and current language cannot diverge and the banner is not needed. Neither is set by default nor by the automatic injection, so the default flow is always: session switch + banner offering to persist.

Language Mismatch Banner

When the user's preferred language (stored in a PreferredLanguage cookie, set by CronosCore) differs from the current page language, a banner appears with two options:

• "Use {language} everywhere" - Calls the CronosWeb.UpdateApplicationLanguage endpoint to persist the current language as the user's Person.ApplicationLanguage
• "Dismiss for now" - Hides the banner until the next page load

Events

The component fires the following custom events:

Translatable Messages

The plugin registers the following client-side messages (en, nl, fr):

• LanguageBanner_Message - The mismatch banner message
• LanguageBanner_UseEverywhere - The persist button label
• LanguageBanner_Dismiss - The dismiss button label
• LanguageBanner_LanguageName_en - Language name for English
• LanguageBanner_LanguageName_nl - Language name for Dutch
• LanguageBanner_LanguageName_fr - Language name for French

Styling

The component uses Shadow DOM. You can customize its appearance via CSS custom properties and ::part() selectors.

CSS Custom Properties

Override these on the host element or any ancestor:

Example:

ts-language-banner {
  --language-banner-primary-bg: var(--theme-color);
  --language-banner-primary-hover-bg: var(--theme-color-lighter);
  --language-banner-bg: var(--theme-color-faint);
}

CSS ::part() Selectors

For full styling control, target individual elements:

Example:

ts-language-banner::part(banner) {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
}

ts-language-banner::part(btn-primary) {
  background-color: white;
  color: #764ba2;
}

Dependencies

• CronosCore (CronosCore#742) - Provides:
  1. PreferredLanguage cookie set on login from Person.ApplicationLanguage (opt-in via PreferredLanguageCookie.Enabled)
  2. CronosWeb.UpdateApplicationLanguage() — endpoint that forwards to CronosCentral via ClientInvoker and refreshes the cookie on success
  3. CronosAdvanced.RegisterLoadUserSettingsHook() (CronosCore.Common 3.31.0+) — used to hide the UserSettings Language field. The generated Service/Plugins/LanguageBanner.g.cs compiles inside your project against the CronosCore version you reference; the package itself declares no CronosCore dependency.

Consuming App Setup

Enable the preferred language cookie in your authenticator service constructor:

public MyAuthenticatorService()
    : base(..., preferredLanguageCookie: PreferredLanguageCookie.Enabled)
{ }

No additional wiring is needed — CronosWeb.UpdateApplicationLanguage() handles the CronosCentral API call and cookie refresh automatically. Requires services.AddCronosCore() to be registered.