In this article, I’ll walk through a clean and production-ready approach to implementing localization in a Blazor Web Application using .NET 8, with support for English (en-US) and Arabic (ar-SA).

This setup is simple, scalable, and suitable for real-world projects.

What This Guide Covers

• Resource-based localization using .resx files

• Switching UI culture at runtime

• Persisting the selected culture using cookies

• Handling Arabic calendars correctly

• Using shared resources across components

Step 1: Create Localization Resources

Start by creating a folder named Resources.

Inside it, add the following files:

• SharedResource.cs (empty marker class)

• SharedResource.en-US.resx

• SharedResource.ar-SA.resx

The SharedResource class is used to group common localized strings across the application.

Example Resource Entry

Important rule:
👉 Keys must be identical across all language files.

Step 2: Configure Localization in Program.cs

Register localization services:

builder.Services.AddLocalization();

Define supported cultures and configure middleware:

var enCulture = new CultureInfo("en-US")
{
    DateTimeFormat = { Calendar = new GregorianCalendar() }
};

var arCulture = new CultureInfo("ar-SA")
{
    DateTimeFormat = { Calendar = new UmAlQuraCalendar() }
};

var supportedCultures = new[] { enCulture, arCulture };

app.UseRequestLocalization(options =>
{
    options.DefaultRequestCulture =
        new RequestCulture(enCulture);

    options.SupportedCultures = supportedCultures;
    options.SupportedUICultures = supportedCultures;
});

This ensures correct date formatting and UI behavior for both cultures.

Step 3: Persist Culture Selection Using Cookies

Blazor does not persist culture changes by default. To handle this, we store the selected culture in a cookie.

Create a JavaScript file named localization.js:

function setCultureCookie(culture) {
    document.cookie =
        `.AspNetCore.Culture=c=${culture}|uic=${culture};path=/;max-age=2592000`;
    location.reload();
}

This ensures the selected culture survives page reloads and navigation.

Step 4: Inject the Localizer Globally

To avoid repeating injections in every component, add this to _Imports.razor:

@inject IStringLocalizer<SharedResource> Localizer

Now the localizer is available across all Razor components.

Step 5: Switch Language from the UI

In MainLayout.razor, inject JavaScript runtime and add a toggle button:

@inject IJSRuntime JSRuntime

<button @onclick="ToggleCulture">
    @Localizer["ToggleLanguage"]
</button>

@code {
    private async Task ToggleCulture()
    {
        var currentCulture =
            CultureInfo.CurrentCulture.Name;

        var newCulture =
            currentCulture == "en-US"
                ? "ar-SA"
                : "en-US";

        await JSRuntime.InvokeVoidAsync(
            "setCultureCookie",
            newCulture);
    }
}

This provides a simple and predictable way to switch languages.

Step 6: Use Localized Text in Components

Example usage in Home.razor:

<h1>@Localizer["Welcome"]</h1>
<p>@Localizer["ExampleText"]</p>

All UI text now comes from centralized resource files.

Source Code

The complete working example is available on GitHub:

👉 [GitHub Repository Link]

You can clone it, run it, and adapt it to your own projects.

Final Thoughts

This approach keeps localization:

• Centralized

• Easy to maintain

• Scalable for additional languages

If you’re building multilingual Blazor applications, setting this up early will save you from painful refactoring later.