Localization

Customize all component labels, integrate with any localization framework, and leverage automatic culture-aware formatting for dates and numbers.

Overview

Blazor Blueprint ships with English defaults for all component chrome — placeholders, button labels, ARIA attributes, pagination text, and empty states. Every string is configurable through IBbLocalizer, an interface registered via DI.

The library does not take a dependency on IStringLocalizer or any specific localization framework. It provides the abstraction — you bring your own localization strategy (resource files, JSON, database, or anything else).

Interactive Demo

Select a language below to see how Blazor Blueprint components adapt. Culture-aware components like the Calendar update month and day names automatically. Label-based components receive translated strings via parameter overrides or IBbLocalizer.

Quick Start

Option A: Use English defaults (no configuration needed)

builder.Services.AddBlazorBlueprintComponents();

Option B: Override specific keys at startup

builder.Services.AddBlazorBlueprintComponents(localizer =>
{
    localizer.Set("DataGrid.NoResultsFound", "Keine Ergebnisse gefunden");
    localizer.Set("DataGrid.Loading", "Laden...");
    localizer.Set("Calendar.GoToPreviousMonth", "Zum vorherigen Monat");
    localizer.Set("DatePicker.Placeholder", "Datum auswählen");
    localizer.Set("Pagination.RowsPerPage", "Zeilen pro Seite");
    localizer.Set("Pagination.PageFormat", "Seite {0} von {1}");
    localizer.Set("FormWizard.Next", "Weiter");
    localizer.Set("FormWizard.Back", "Zurück");
});

This registers DefaultBbLocalizer as a singleton with your overrides applied. All components resolve their labels through the IBbLocalizer interface.

How it works internally

Components inject IBbLocalizer and look up strings by key. Keys use dot notation: ComponentName.PropertyName.

@inject IBbLocalizer Localizer

<div>@Localizer["DataGrid.Loading"]</div>
<span>@Localizer["DataGrid.ShowingRange", start, end, total]</span>

Format Strings

Some keys use string.Format placeholders for dynamic values. Argument order can be rearranged per language, making these fully translatable:

// Some keys use string.Format placeholders for dynamic values:
// "Showing {0}–{1} of {2}"    → Localizer["DataGrid.ShowingRange", 1, 10, 100]
// "Remove {0}"                → Localizer["TagInput.RemoveTag", "blazor"]
// "{0} day(s) selected"       → Localizer["DateRangePicker.DaysSelected", 5]

// Argument order can be rearranged per language, making these fully translatable.
localizer.Set("DataGrid.ShowingRange", "Zeige {0}–{1} von {2}");
localizer.Set("TagInput.RemoveTag", "{0} entfernen");

Integration with IStringLocalizer

Create a custom IBbLocalizer implementation that delegates to IStringLocalizer<T>:

public class AppBbLocalizer(IStringLocalizer<SharedResources> localizer)
    : DefaultBbLocalizer
{
    public override string this[string key] =>
        localizer[key] is { ResourceNotFound: false } found ? found.Value : base[key];

    public override string this[string key, params object[] arguments] =>
        localizer[key, arguments] is { ResourceNotFound: false } found
            ? found.Value : base[key, arguments];
}

Register it as scoped for per-circuit culture switching:

builder.Services.AddBlazorBlueprintComponents();
builder.Services.AddScoped<IBbLocalizer, AppBbLocalizer>();

When CultureInfo.CurrentUICulture changes, IStringLocalizer automatically resolves the correct language from your .resx files. Keys that don't exist in your resource files fall back to the English defaults in DefaultBbLocalizer.

Resource file setup

Create .resx files with keys matching the dot-notation format:

Name                          | Value
------------------------------|-------------------------------
DataGrid.Loading              | Laden...
DataGrid.NoResultsFound       | Keine Ergebnisse gefunden
DataGrid.ShowingRange         | Zeige {0}–{1} von {2}
Combobox.Placeholder          | Auswählen...
Pagination.RowsPerPage        | Zeilen pro Seite

Per-Component Parameter Overrides

Many localizable strings are also exposed as component [Parameter] properties. When set, the parameter value always takes priority over the localizer.

<!-- This Combobox uses a custom message regardless of IBbLocalizer -->
<BbCombobox TValue="string"
            Options="options"
            EmptyMessage="No matching frameworks found"
            @bind-Value="selected" />

<!-- This one uses whatever Localizer["Combobox.EmptyMessage"] returns -->
<BbCombobox TValue="string"
            Options="options"
            @bind-Value="selected" />

Resolution Order

Culture-Aware Formatting

Several components automatically adapt to CultureInfo.CurrentCulture without any label configuration:

Singleton vs Scoped Registration

Singleton (default)

Best for apps that serve a single language or determine the language once at startup. The configuration action runs once, and all components share the same localizer instance.

builder.Services.AddBlazorBlueprintComponents(localizer =>
{
    localizer.Set("FormWizard.Next", "Weiter");
    localizer.Set("FormWizard.Back", "Zurück");
});

Scoped

Required when users can switch languages at runtime. Register a custom IBbLocalizer as scoped so each Blazor Server circuit resolves strings based on the current culture. The scoped registration overrides the default singleton.

builder.Services.AddBlazorBlueprintComponents();
builder.Services.AddScoped<IBbLocalizer, AppBbLocalizer>();

Available Keys

All keys use dot notation: ComponentName.PropertyName. Keys marked with (format) accept string.Format arguments.