AspNetCore.Docs/aspnetcore/blazor/globalization-localization.md

title	author	description	monikerRange	ms.author	ms.custom	ms.date	no-loc	uid
ASP.NET Core Blazor globalization and localization	guardrex	Learn how to make Razor components accessible to users in multiple cultures and languages.	>= aspnetcore-3.1	riande	mvc	06/04/2020	Kestrel appsettings.json ASP.NET Core Identity cookie Cookie Blazor Blazor Server Blazor WebAssembly Identity Let's Encrypt Razor SignalR	blazor/globalization-localization

ASP.NET Core Blazor globalization and localization

Razor components can be made accessible to users in multiple cultures and languages. The following .NET globalization and localization scenarios are available:

• .NET's resources system
• Culture-specific number and date formatting

A limited set of ASP.NET Core's localization scenarios are currently supported:

• xref:Microsoft.Extensions.Localization.IStringLocalizer and xref:Microsoft.Extensions.Localization.IStringLocalizer%601 are supported in Blazor apps.
• xref:Microsoft.AspNetCore.Mvc.Localization.IHtmlLocalizer, xref:Microsoft.AspNetCore.Mvc.Localization.IViewLocalizer, and Data Annotations localization are ASP.NET Core MVC scenarios and not supported in Blazor apps.

For more information, see xref:fundamentals/localization.

Globalization

Blazor's @bind functionality performs formats and parses values for display based on the user's current culture.

The current culture can be accessed from the xref:System.Globalization.CultureInfo.CurrentCulture?displayProperty=fullName property.

xref:System.Globalization.CultureInfo.InvariantCulture?displayProperty=nameWithType is used for the following field types (<input type="{TYPE}" />):

• date
• number

The preceding field types:

• Are displayed using their appropriate browser-based formatting rules.
• Can't contain free-form text.
• Provide user interaction characteristics based on the browser's implementation.

The following field types have specific formatting requirements and aren't currently supported by Blazor because they aren't supported by all major browsers:

• datetime-local
• month
• week

@bind supports the @bind:culture parameter to provide a xref:System.Globalization.CultureInfo?displayProperty=fullName for parsing and formatting a value. Specifying a culture isn't recommended when using the date and number field types. date and number have built-in Blazor support that provides the required culture.

Localization

Blazor WebAssembly

Blazor WebAssembly apps set the culture using the user's language preference.

To explicitly configure the culture, set xref:System.Globalization.CultureInfo.DefaultThreadCurrentCulture?displayProperty=nameWithType and xref:System.Globalization.CultureInfo.DefaultThreadCurrentUICulture?displayProperty=nameWithType in Program.Main.

::: moniker range=">= aspnetcore-5.0"

By default, Blazor WebAssembly carries minimal globalization resources required to display values, such as dates and currency, in the user's culture. Applications that must support dynamically changing the culture should configure BlazorWebAssemblyLoadAllGlobalizationData in the project file:

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

Blazor WebAssembly can also be configured to launch using a specific application culture using options passed to Blazor.start. For instance, the sample below shows an app configured to launch using the en-GB culture:

<script src="_framework/blazor.webassembly.js" autostart="false"></script>
<script>
  Blazor.start({
    applicationCulture: 'en-GB'
  });
</script>

The value for applicationCulture should conform to the BCP-47 language tag format.

If the app doesn't require localization, you may configure the app to support the invariant culture, which is based on the en-US culture:

<PropertyGroup>
  <InvariantGlobalization>true</InvariantGlobalization>
</PropertyGroup>

::: moniker-end

::: moniker range="< aspnetcore-5.0"

By default, the Intermediate Language (IL) Linker configuration for Blazor WebAssembly apps strips out internationalization information except for locales explicitly requested. For more information, see xref:blazor/host-and-deploy/configure-linker#configure-the-linker-for-internationalization.

::: moniker-end

While the culture that Blazor selects by default might be sufficient for most users, consider offering a way for users to specify their preferred locale. For a Blazor WebAssembly sample app with a culture picker, see the LocSample localization sample app.

Blazor Server

Blazor Server apps are localized using Localization Middleware. The middleware selects the appropriate culture for users requesting resources from the app.

The culture can be set using one of the following approaches:

• Cookies
• Provide UI to choose the culture

For more information and examples, see xref:fundamentals/localization.

Cookies

A localization culture cookie can persist the user's culture. The Localization Middleware reads the cookie on subsequent requests to set the user's culture.

Use of a cookie ensures that the WebSocket connection can correctly propagate the culture. If localization schemes are based on the URL path or query string, the scheme might not be able to work with WebSockets, thus fail to persist the culture. Therefore, use of a localization culture cookie is the recommended approach.

Any technique can be used to assign a culture if the culture is persisted in a localization cookie. If the app already has an established localization scheme for server-side ASP.NET Core, continue to use the app's existing localization infrastructure and set the localization culture cookie within the app's scheme.

The following example shows how to set the current culture in a cookie that can be read by the Localization Middleware. Create a Razor expression in the Pages/_Host.cshtml file immediately inside the opening <body> tag:

@using System.Globalization
@using Microsoft.AspNetCore.Localization

...

<body>
    @{
        this.HttpContext.Response.Cookies.Append(
            CookieRequestCultureProvider.DefaultCookieName,
            CookieRequestCultureProvider.MakeCookieValue(
                new RequestCulture(
                    CultureInfo.CurrentCulture,
                    CultureInfo.CurrentUICulture)));
    }

    ...
</body>

Localization is handled by the app in the following sequence of events:

1. The browser sends an initial HTTP request to the app.
2. The culture is assigned by the Localization Middleware.
3. The Razor expression in the _Host page (_Host.cshtml) persists the culture in a cookie as part of the response.
4. The browser opens a WebSocket connection to create an interactive Blazor Server session.
5. The Localization Middleware reads the cookie and assigns the culture.
6. The Blazor Server session begins with the correct culture.

When working with a xref:Microsoft.AspNetCore.Mvc.Razor.RazorPage, use the xref:Microsoft.AspNetCore.Mvc.Razor.RazorPage.Context property:

@{
    this.Context.Response.Cookies.Append(
        CookieRequestCultureProvider.DefaultCookieName,
        CookieRequestCultureProvider.MakeCookieValue(
            new RequestCulture(
                CultureInfo.CurrentCulture,
                CultureInfo.CurrentUICulture)));
}

Provide UI to choose the culture

To provide UI to allow a user to select a culture, a redirect-based approach is recommended. The process is similar to what happens in a web app when a user attempts to access a secure resource. The user is redirected to a sign-in page and then redirected back to the original resource.

The app persists the user's selected culture via a redirect to a controller. The controller sets the user's selected culture into a cookie and redirects the user back to the original URI.

Establish an HTTP endpoint on the server to set the user's selected culture in a cookie and perform the redirect back to the original URI:

[Route("[controller]/[action]")]
public class CultureController : Controller
{
    public IActionResult SetCulture(string culture, string redirectUri)
    {
        if (culture != null)
        {
            HttpContext.Response.Cookies.Append(
                CookieRequestCultureProvider.DefaultCookieName,
                CookieRequestCultureProvider.MakeCookieValue(
                    new RequestCulture(culture)));
        }

        return LocalRedirect(redirectUri);
    }
}

[!WARNING] Use the xref:Microsoft.AspNetCore.Mvc.ControllerBase.LocalRedirect%2A action result to prevent open redirect attacks. For more information, see xref:security/preventing-open-redirects.

If the app isn't configured to process controller actions:

• Add MVC services to the service collection in Startup.ConfigureServices:

  services.AddControllers();
  

• Add controller endpoint routing in Startup.Configure:

  app.UseEndpoints(endpoints =>
  {
      endpoints.MapControllers();
      endpoints.MapBlazorHub();
      endpoints.MapFallbackToPage("/_Host");
  });
  

The following component shows an example of how to perform the initial redirection when the user selects a culture:

@inject NavigationManager NavigationManager

<h3>Select your language</h3>

<select @onchange="OnSelected">
    <option>Select...</option>
    <option value="en-US">English</option>
    <option value="fr-FR">Français</option>
</select>

@code {
    private void OnSelected(ChangeEventArgs e)
    {
        var culture = (string)e.Value;
        var uri = new Uri(NavigationManager.Uri)
            .GetComponents(UriComponents.PathAndQuery, UriFormat.Unescaped);
        var query = $"?culture={Uri.EscapeDataString(culture)}&" +
            $"redirectUri={Uri.EscapeDataString(uri)}";

        NavigationManager.NavigateTo("Culture/SetCulture" + query, forceLoad: true);
    }
}

Additional resources

• Set the app base path
• xref:fundamentals/localization