Localization

Supported languages

Choose the language

In Blazor WebAssembly set the culture before the application runs. In a server application use request localization, so each user gets the culture of their request.

// Blazor WebAssembly: Program.cs
var culture = new CultureInfo("es");
CultureInfo.DefaultThreadCurrentCulture = culture;
CultureInfo.DefaultThreadCurrentUICulture = culture;

// Blazor Server: Program.cs
app.UseRequestLocalization(new RequestLocalizationOptions()
    .SetDefaultCulture("en-GB")
    .AddSupportedCultures("en-GB", "es", "ja")
    .AddSupportedUICultures("en-GB", "es", "ja"));

To pin every component to one culture whatever the application is running under, set Culture on the options. It applies to both the text and the formatting.

builder.Services.AddTwBlazor(options =>
{
    options.Localization.Culture = new CultureInfo("ja");
}, Theme.CreateTheme);

Blazor WebAssembly only downloads the language files for the culture the application starts with. Changing the language while it runs needs a page reload, and BlazorWebAssemblyLoadAllGlobalizationData has to be on for cultures outside the default set. This is how Blazor localization works in general and is not specific to twblazor.

Right to left languages

@* MainLayout.razor *@
<TwDirectionProvider>
    @Body
    <TwToastProvider />
    <TwDialogProvider />
</TwDirectionProvider>

To set the direction whatever the culture, use options.Localization.Direction.

builder.Services.AddTwBlazor(options =>
{
    options.Localization.Direction = TextDirection.RightToLeft;
}, Theme.CreateTheme);

Change or add text with your own resource files

MyApp/
  Resources/
    TwBlazorStrings.resx        the neutral file, used when no language file matches
    TwBlazorStrings.nl.resx     Dutch
    TwBlazorStrings.sv.resx     Swedish

Then register the file family. Only the keys you want to change need to be there. Anything missing falls back to twblazor's own file for that language, then to English.

using System.Resources;

builder.Services.AddTwBlazor(options =>
{
    options.Localization.AddResource(
        new ResourceManager("MyApp.Resources.TwBlazorStrings", typeof(Program).Assembly));
}, Theme.CreateTheme);

A value with placeholders keeps them, so Page {0} of {1} becomes Pagina {0} van {1}. Text that counts something has a singular and a plural key, such as Sidebar_ResultsOne and Sidebar_ResultsOther.

<!-- Resources/TwBlazorStrings.nl.resx -->
<data name="Common_Close" xml:space="preserve">
  <value>Sluiten</value>
</data>
<data name="Pagination_PageStatus" xml:space="preserve">
  <value>Pagina {0} van {1}</value>
</data>

Several file families can be registered. They are searched last added first. The full list of keys, with the English text of each, is the TwStrings class and TwBlazorStrings.resx.

Change text on one component

A component parameter always wins over the resource files, so a single component can say something different from the rest of the application.

<TwSelect T="string" Values="@countries" Placeholder="Choose a country" />

<TwDatePicker @bind-SelectedDate="date" Format="yyyy-MM-dd" />

<TwTimePicker @bind-SelectedTime="time" Is12HourFormat="true" />

Date and time formats

When the application has no culture of its own (the invariant culture), twblazor uses British formats: a 24 hour clock, day before month, and weeks that start on Monday.

builder.Services.AddTwBlazor(options =>
{
    options.Localization.Formats.FirstDayOfWeek = DayOfWeek.Sunday;
    options.Localization.Formats.Use12HourClock = true;
    options.Localization.Formats.LongDate = "dddd, d MMMM yyyy";
    options.Localization.Formats.DateInput = "dd.MM.yyyy";
}, Theme.CreateTheme);

The picker input formats are the ones users type, so they stay fixed unless you change them: the date pickers use the theme's dd/MM/yyyy and the time pickers use a 24 hour clock, whatever the culture. To make the pickers type and parse the way a culture writes dates, copy its patterns in one call.

// For en-US this sets M/d/yyyy, h:mm tt and a 12 hour clock.
options.Localization.Formats.UseCultureInputFormats(new CultureInfo("en-US"));

A format can also live in a resource file, so each language carries its own. Add an entry named Format_ShortTime, Format_LongDate and so on to the language's file. A value set on the options wins over the resource file, which wins over the culture. A component parameter such as Format or Is12HourFormat wins over all three.

Use your own localizer

public class MyLocalizer(TwBlazorOptions options, IStringLocalizer<SharedResource> strings)
    : TwLocalizer(options)
{
    protected override string? GetString(string key, CultureInfo culture)
    {
        var text = strings[key];
        return text.ResourceNotFound ? base.GetString(key, culture) : text.Value;
    }
}

builder.Services.AddScoped<ITwLocalizer, MyLocalizer>();
builder.Services.AddTwBlazor(_ => { }, Theme.CreateTheme);

The same service is available to your own components, with the same keys and formats.

@inject ITwLocalizer Localizer

<button aria-label="@Localizer[TwStrings.Common_Close]">×</button>
<span>@Localizer.Formats.Format(DateTime.Today, Localizer.Formats.LongDate)</span>