Internalization and localization

Internationalization, usually referred to by the word i18n, is the process of enabling your website to display in different languages and different formats, like date format and number format. L10n is the process of translating from one language to another with its national formats like date format and number format. In this tutorial, you will discover:

• How Blazor WebAssembly identifies a region?
• Required NuGet libraries.
• Translation approaches.
• Language selection strategies.
• Resource loading strategies.
• Enable multiple languages in your website.

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

How Blazor WebAssembly identifies a region?

Blazor WebAssembly identifies a region by CultureInfo.DefaultThreadCurrentCulture and CultureInfo.DefaultThreadCurrentUICulture. When you set a CultureInfo to both properties, the formats of dates, times, numbers and currencies will be changed accordingly.

Required NuGet libraries

Before you begin, you need to install Microsoft.Extensions.Localization. You will need more packages based on your approach.

Translation approaches

There are 2 approaches for internationalization of your website:

• Defer Translation: This approach is not SPA friendly because whenever the user select a language, the entire website needs to be reloaded to take effect. All the resources to translate the website will be loaded at the first load. The following video illustrates this approach:

• Instant Translation: This approach is SPA friendly because whenever the user select a language, the entire website will take effect immediately. You can also choose to load all the resources at the first load or lazy load with memory cache. The following video illustrates 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 confliction 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. In those cases, you need to select one language to display your website. It's your job to priority those language selection strategies.

Resource loading strategies

A resource is a file with the content is a collection of keys and values for translation for a specific language. For example, your website has 3 languages and 2 components, then each component needs 4 resource files: A fallback resource and 3 resource files for 3 languages. In total, you will have 8 resource files (because you have 2 components and each component has 4 resource files). The resource files need to be loaded before you can display the translated text to the UI. There are 2 loading strategies for Blazor WebAssembly:

• Eager loading: All the resource files will be loaded at the first load of the website, the resource file will have .resx file extension. When building the website, .NET CLI will compile .resx to .dll file and embedded to the source code. For example, your website has 10 components in 3 languages and the user requested 1 component, you will have to load all 40 resource files. This strategy can be used with any translation approach.
• Lazy loading: Only the requested resource files will be loaded. Once loaded, the resource file will be cached at the browser memory so that when the user changes the language, you don't need to load the resource again. The resource file can have different extension like .json and .yml. For example, your website has 10 components in 3 languages and the user requested 1 component, you will have to load 1 resource files. This strategy can only be used with the Instant Translation approach.

Enable multiple languages in your website

1. Install the required NuGet library Microsoft.Extensions.Localization.
2. Edit the csproj.cs file. Add the following code to the csproj.cs:

<PropertyGroup>
    ...
    <BlazorWebAssemblyLoadAllGlobalizationData>true</BlazorWebAssemblyLoadAllGlobalizationData>
</PropertyGroup>

Here is how to edit your csproj.cs file: Right click your project and Edit Project File.

3. In your component, inject IStringLocalizer<T> with T is your component type. For example, in your ChangeLanguageDemonstrate.razor:

@inject IStringLocalizer<ChangeLanguageDemonstrate> Localizer

4. Use the IStringLocalizer to serve the text in multiple language. For example:

@Localizer["String1"]

The String1 in the above example is your resource key.

5. Implement a translation approach. This step will be in the next tutorial.

You can pass the parameter to the localizer as well. To use the parameter, you need to put a placeholder in the translated text. For example: "Hello {0}, {1}". Then you can pass parameters to replace the placeholder like this @Localizer["String1", "Blazor School", "Blazor School Books"].