Setting the App's Language
BPT ships with eight supported cultures out of the box and gives you five different ways to pick which one is active — from a visual picker your users see, to URL parameters, to programmatic overrides driven by tenant config.
IsabyteCulture is the catalog of supported cultures.
IsabyteCultureState is the cascading service that tracks the currently active one and translates
resource keys. IsabyteLanguage is the optional visual picker your users interact with. Each of the
five "ways to set the language" below ultimately funnels into the same IsabyteCultureState.
Supported cultures
BPT ships with eight cultures, each with its own resource translations, emoji + SVG flag, currency symbol, and number format defaults:
| Code | Language | Currency |
|---|---|---|
nb-NO | Norwegian Bokmål | NOK (kr) |
en-GB | English (UK) | GBP (£) |
en-US | English (US) | USD ($) |
sv-SE | Swedish | SEK (kr) |
de-DE | German | EUR (€) |
fr-FR | French | EUR (€) |
es-ES | Spanish | EUR (€) |
zh-CN | Chinese (Simplified) | CNY (¥) |
The catalog lives in IsabyteCulture.GetSupportedCultures(). Any culture code not in this list falls back to the closest supported neighbor via IsabyteCulture.MapToSupported(...) — for example "en-AU" maps to en-US and "nb" maps to nb-NO.
The five ways to set the active culture
Way 1: Drop in the IsabyteLanguage picker
The simplest path. Add the picker to your MainLayout and users pick their own language. Their selection automatically persists across visits via localStorage.
@using Isabyte.PowerTools.Components.Controls
<!-- Compact: just a flag icon that opens a dropdown -->
<IsabyteLanguage DisplayMode="LanguageDisplayMode.Compact" />
<!-- Full: flag + language name + culture code -->
<IsabyteLanguage DisplayMode="LanguageDisplayMode.Full"
OnCultureChanged="OnCultureChanged" />
@code {
private void OnCultureChanged(string code)
{
// code = "nb-NO", "en-GB", etc. Optional — the picker already updates IsabyteCultureState.
}
}DecimalSeparator and ThousandsSeparator on either IsabyteLanguage or
directly on IsabyteCultureState to override the culture's defaults without changing the language.
Way 2: Pin the culture programmatically
When the active language is decided by application logic (per-tenant config, user profile in DB, A/B bucket), set it once on IsabyteRootComponent at the top of your app:
<!-- App.razor (or MainLayout.razor) -->
<IsabyteRootComponent CultureCode="@_tenantCulture">
<Router AppAssembly="typeof(Program).Assembly">
...
</Router>
</IsabyteRootComponent>
@code {
[Inject] ITenantService TenantService { get; set; } = default!;
private string _tenantCulture = "en-US";
protected override async Task OnInitializedAsync()
{
var tenant = await TenantService.GetCurrentAsync();
_tenantCulture = tenant.DefaultCultureCode; // e.g. "nb-NO"
}
}For runtime changes (a user toggles their preferred language inside the app), inject IsabyteCultureState and call SetCurrentCulture:
@inject IsabyteCultureState CultureState
<button @onclick='() => CultureState.SetCurrentCulture("sv-SE")'>
Switch to Swedish
</button>Way 3: URL query parameter
For shareable language links, deep-links from email, or per-tenant subdomain routing, IsabyteRootComponent reads a ?culture=... query parameter on first render:
https://example.com/products?culture=nb-NO
https://example.com/products?culture=zh-CNThis takes precedence over the user's saved localStorage preference for that page load. Useful for landing pages where the language is part of the campaign URL.
Way 4: localStorage persistence
By default the IsabyteLanguage picker persists the user's choice to localStorage under the key isabyte_current_culture. On subsequent visits, IsabyteLanguage reads that value in OnAfterRenderAsync and restores the language.
You can interact with this key from any other JS code on the page — for instance, syncing the language with a server-side cookie:
// Read what IsabyteLanguage has stored.
const culture = localStorage.getItem("isabyte_current_culture");
// Mirror to a server-readable cookie so SSR-rendered pages know the culture too.
document.cookie = `culture=${culture}; path=/; max-age=31536000`;Way 5: Auto-detect from the browser
If none of the above apply (no URL param, no localStorage, no programmatic override), BPT falls back to the browser's navigator.language via IsabyteCulture.MapToSupported(...):
| Browser sends | BPT resolves to |
|---|---|
en-AU, en-CA, en-IN | en-US |
nb, nn, no | nb-NO |
de-AT, de-CH | de-DE |
zh-TW, zh-HK | zh-CN |
| anything else | en-US |
Reading the active culture in your own components
IsabyteCultureState is registered as a root cascading value, so any component — Server or WebAssembly — can pick it up:
@code {
[CascadingParameter] public IsabyteCultureState? CultureState { get; set; }
private string Greeting => CultureState?.CurrentCulture switch
{
"nb-NO" => "Hei!",
"sv-SE" => "Hej!",
"de-DE" => "Hallo!",
"zh-CN" => "你好!",
_ => "Hello!"
};
// Look up translations from BPT's resx files (Isabyte.PowerTools.Components.Common.Resources.IsabyteTranslations).
private string L(string key, string fallback)
=> CultureState?.T(key) ?? fallback;
}Quick comparison
| Mechanism | Persists? | Best for |
|---|---|---|
<IsabyteLanguage /> picker | localStorage | End-user choice. The default for most apps. |
IsabyteRootComponent CultureCode | Per-render | App-wide lock driven by tenant or user profile. |
IsabyteCultureState.SetCurrentCulture(...) | In-memory + localStorage | Runtime switching from your own UI. |
?culture=... query param | Per-request | Email links, campaign landing pages, tenant subdomains. |
| Browser auto-detect | None (computed each time) | Anonymous first-time visitors who haven't chosen yet. |
isabyteCulture.js broadcasts a CustomEvent whenever the culture changes. This means
a Server-rendered island and a WebAssembly-rendered island on the same page see culture switches in real
time without page reload — no extra wiring needed.
