Multilingual website

We live in a multilingual world, so offering your website in multiple languages is a great way to make it more user-friendly and connect with new audiences. To help you be successful, we’re going to share a detailed guide on how to create a multi language website. In this tutorial, we will cover:

• How Blazor Server identifies the display language?
• What do you need to pay attention when making a multi language website?
• Translation approaches.
• Language selection strategies.
• Create resources for web pages.

You can download the example code used in this topic on GitHub.

How Blazor Server identifies the display language?

Blazor Server identifies the display language based on the value of CultureInfo.CurrentCulture and CultureInfo.CurrentUICulture. The value set to those properties are strings. This string is a language tag which includes 2 information:

• What language is it?
• What location is it?

This is an example language tag: "en-US": the "en" indicates that the language is English, the "US" indicates that the language is used in "America". You can see the list of language tags in Microsoft Learn There is a rare case that you need to create your own language and the location, but that part does not include in this tutorial.

What do you need to pay attention when making a multi language website?

When creating a multi language website, you need to pay attention to:

• Language selection strategy: How can Blazor Server select the language to display to the end user?
• Translation approach: When a language is selected, how can Blazor Server fetch the resource files and render the web page?

Translation approaches

There are 2 approaches when implement a multilingual website with Blazor Server, and it affects directly to the user experience.

• Deferred translation: When a user selects a language, the website acknowledges and set it as the language when the user revisits the website; Meaning that when a user selects a language, the user must refresh the website for it to takes effect. The following video demonstrates this approach:

• Instant translation: When a user selects a language, Blazor Server acknowledges and re-renders the web page immediately. The following video demonstrates this approach:

Language selection strategies

A user can provide their preferred language in many ways:

• Browser settings.
• Stored language in local storage.
• Stored language in cookie.
• Embedded the language in the URL.

There maybe a conflict between those ways. For example, a user may have entered your website with the language "en-US" in their URL, but their browser is set to French. Another example would be a user visits your website and select "en-US", then you store the language in their local storage; Later on, they revisit your website with the "fr" language in their URL. There is no standard strategy, every website resolves the conflict and select a language to display differently, and you need to do the same.

Create resources for web pages

Each language tag is pair with a resource file. A resource file is an XML formatted file with the .resx extension.

1. Create a new folder with the same level as the Page folder. For example, the BlazorSchoolResources folder:

2. Create a folder structure the same as the components you want to translate. For example, if the path to your component is in the Pages folder then you need to put all the resources file under BlazorSchoolResources/Pages; If the path to your component is in the Shared/MyComponent folder then you need to put all the resources file under BlazorSchoolResources/Shared/MyComponent.

3. Create resource files. The resource file must follow the pattern: <ComponentName>.<LanguageTag>.resx. For example, if your component is MyComponent.razor and you support French (fr) and English (en-US) then create 2 resource files with the name MyComponent.fr.resx and MyComponent.en-US.resx.
4. Add keys and values to all the resource files.

5. Register at Program.cs. For example:

builder.Services.AddLocalization(options => options.ResourcesPath = "BlazorSchoolResources");
...
app.UseRequestLocalization();

6. In the component you want to translate, inject the IStringLocalizer<Your_Component>. For example, in the MyComponent:

@using Microsoft.Extensions.Localization
@inject IStringLocalizer<MyComponent> Localizer

@Localizer["String1"]

The String1 in the example is the key you defined in the resource file.