Multilingual website

🟨 Slightly different to Blazor WebAssembly

If you're looking to expand your website's reach and cater to an international audience, creating a multilingual website is an excellent strategy. In this tutorial, we'll guide you through the process of building a Blazor application that can support multiple languages.

• How multilingual works in Blazor Server?
• Key considerations when creating a multilingual website.
• Language selection strategies.
• Translation approaches.
• Create .resx files for website localization
• Key differences between Blazor WebAssembly and Blazor Server.

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

How multilingual works in Blazor Server?

Multilingual works can be achieved in four steps:

1. Identifying the language associated with the region: Since a country may have multiple languages, Blazor Server uses CultureInfo.CurrentCulture and CultureInfo.CurrentUICulture to determine the current region. Here is an example language tag, en-US: The en indicates that the language is English, and the US indicates that the language is used in America. You can find a list of language tags on Microsoft Learn. Although it is a rare case, you may need to create your own language and location, but that part is not included in this tutorial.
2. Locating the corresponding resource file using a key: Resource files can be in various formats such as .resx, .json, .yml, etc. and their structure may differ as well. Translated keys may be nested, such as Index.HelloWorld or a flat format like HelloWorld or even spread across multiple files. For the purpose of this tutorial, we will be using .resx resource files.
3. Using parameters in addition to the key to translate the text: For example, in Chinese, the 31st day is "日31," while in English, it is "31st."
4. Displaying the translated text.

Key considerations when creating a multilingual website

The most important thing to keep in mind when creating a multilingual website are:

1. Language selection strategy.
2. Translation approach.

Language selection strategies

When creating a multilingual website, developers can use different methods to determine the user's preferred language, such as cookies, browser language, local storage, or the language in the URL. For example, if a user in France visits a website with their browser language set to French, the website can detect this and display the website content in French by default.

However, conflicts may arise when these methods produce different results for the user's preferred language. For instance, if a user's browser language is set to French, but they have previously selected English as their preferred language in the website's settings, there may be a conflict between the two methods.

To resolve such conflicts, developers can prioritize one method over others based on factors such as the reliability of the data source and the user's past language selection history. For instance, if the user has consistently chosen English as their preferred language in the website's settings, the website can prioritize that selection over their browser language.

Translation approaches

There are 2 approaches to translation in Blazor:

1. Deferred translation: When a user selects a language, the website saves it as a preference and remembers it for future visits. However, the language selection may not take effect until the user refreshes the website.

2. Instant translation: With instant translation, when a user selects a language, Blazor immediately updates and renders the web page in the selected language without requiring the user to refresh the website.

Create .resx files for website localization

A .resx file represents a Blazor component in a single language. For instance, if your MyBlazorComponent supports both English and French, then you will have MyBlazorComponent.en.resx and MyBlazorComponent.fr.resx as resource files. There are two ways to organize resource files: centralized and distributed.

Centralized resource

For centralized resource organization, all resource files are placed in the same folder as the component file, as illustrated in the following image:

To register resources for centralization, you can use the following code:

builder.Services.AddLocalization();
...
app.UseRequestLocalization();

Distributed resource

Centralizing resources can pose maintenance challenges. To address this, resource files can be distributed into a separate folder from the component and the component folder tree can be reconstructed inside that folder, as shown in the following image:

To register resources for distributed organization, you can use the following code:

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

In this case, the resource files are located in a folder called BlazorSchoolResources which is separate from the component folder.

.resx file structure

To create a resource file, you must adhere to the naming convention: <ComponentName>.<Language>.resx. For instance, if your component is named MyComponent and you support French (fr) and English (en-US), then create two resource files named MyComponent.fr.resx and MyComponent.en-US.resx.

A resource is a collection of key-value pairs where the keys are consistent across all resource files and are used to retrieve the corresponding values that will be displayed to the user.

Key differences between Blazor WebAssembly and Blazor Server

When working with Blazor Server, you'll need to use CultureInfo.CurrentCulture and CultureInfo.CurrentUICulture, rather than CultureInfo.DefaultThreadCurrentCulture and CultureInfo.DefaultThreadCurrentUICulture as you would with Blazor WebAssembly. Additionally, the project preparation steps are completely different.