aspnetcore/fundamentals/localization/select-language-culture.md
:::moniker range=">= aspnetcore-8.0"
Hisham Bin Ateya, Damien Bowden, Bart Calixto, Nadeem Afana, and Rick Anderson
One task for localizing an app is to implement a strategy for selecting the appropriate culture for each response the app returns.
The current culture on a request is set in the localization Middleware. The localization middleware is enabled in Program.cs. The localization middleware must be configured before any middleware that might check the request culture (for example, app.UseMvcWithDefaultRoute()).
xref:Microsoft.AspNetCore.Builder.ApplicationBuilderExtensions.UseRequestLocalization%2A initializes a xref:Microsoft.AspNetCore.Builder.RequestLocalizationOptions object. On every request the list of xref:Microsoft.AspNetCore.Localization.RequestCultureProvider in the xref:Microsoft.AspNetCore.Builder.RequestLocalizationOptions is enumerated and the first provider that can successfully determine the request culture is used. The default providers come from the RequestLocalizationOptions class:
The default list goes from most specific to least specific. Later in the article you'll see how you can change the order and even add a custom culture provider. If none of the providers can determine the request culture, the xref:Microsoft.AspNetCore.Builder.RequestLocalizationOptions.DefaultRequestCulture is used.
Some apps will use a query string to set the xref:System.Globalization.CultureInfo. For apps that use the cookie or Accept-Language header approach, adding a query string to the URL is useful for debugging and testing code. By default, the xref:Microsoft.AspNetCore.Localization.QueryStringRequestCultureProvider is registered as the first localization provider in the RequestCultureProvider list. You pass the query string parameters culture and ui-culture. The following example sets the specific culture (language and region) to Spanish/Mexico:
http://localhost:5000/?culture=es-MX&ui-culture=es-MX
If only culture or ui-culture is passed in, the query string provider sets both values using the one passed in. For example, setting just the culture will set both the Culture and the UICulture:
http://localhost:5000/?culture=es-MX
Production apps will often provide a mechanism to set the culture with the ASP.NET Core culture cookie. Use the xref:Microsoft.AspNetCore.Localization.CookieRequestCultureProvider.MakeCookieValue%2A method to create a cookie.
The xref:Microsoft.AspNetCore.Localization.CookieRequestCultureProvider xref:Microsoft.AspNetCore.Localization.CookieRequestCultureProvider.DefaultCookieName returns the default cookie name used to track the user's preferred culture information. The default cookie name is .AspNetCore.Culture.
The cookie format is c=%LANGCODE%|uic=%LANGCODE%, where c is Culture and uic is UICulture, for example:
c=en-UK|uic=en-US
If only one of the cultures is provided and the other is empty, the provided culture is used for both culture and UI culture.
The Accept-Language header is settable in most browsers and was originally intended to specify the user's language. This setting indicates what the browser has been set to send or has inherited from the underlying operating system. The Accept-Language HTTP header from a browser request isn't an infallible way to detect the user's preferred language (see Setting language preferences in a browser). A production app should include a way for a user to customize their choice of culture.
Search Settings for Preferred languages.
The preferred languages are listed in the Preferred languages box.
Select Add languages to add to the list.
Select More actions … next to a language to change the order of preference.
The Content-Language entity header:
Entity headers are used in both HTTP requests and responses.
The Content-Language header can be added by setting the property xref:Microsoft.AspNetCore.Builder.RequestLocalizationOptions.ApplyCurrentCultureToResponseHeaders.
Adding the Content-Language header:
Content-Language header with the CurrentUICulture.Content-Language explicitly.app.UseRequestLocalization(new RequestLocalizationOptions
{
ApplyCurrentCultureToResponseHeaders = true
});
The xref:Microsoft.AspNetCore.Localization.Routing.RouteDataRequestCultureProvider sets the culture based on the value of the culture route value. See Url culture provider using middleware as filters for information on:
RouteDataRequestCultureProvider to set the culture of an app from the url.See Applying the RouteDataRequest CultureProvider globally with middleware as filters for information on how to apply the RouteDataRequestCultureProvider globally.
Suppose you want to let your customers store their language and culture in your databases. You could write a provider to look up these values for the user. The following code shows how to add a custom provider:
private const string enUSCulture = "en-US";
services.Configure<RequestLocalizationOptions>(options =>
{
var supportedCultures = new[]
{
new CultureInfo(enUSCulture),
new CultureInfo("fr")
};
options.DefaultRequestCulture = new RequestCulture(culture: enUSCulture, uiCulture: enUSCulture);
options.SupportedCultures = supportedCultures;
options.SupportedUICultures = supportedCultures;
options.AddInitialRequestCultureProvider(new CustomRequestCultureProvider(async context =>
{
// My custom request culture logic
return await Task.FromResult(new ProviderCultureResult("en"));
}));
});
Use RequestLocalizationOptions to add or remove localization providers.
xref:Microsoft.AspNetCore.Builder.RequestLocalizationOptions has three default request culture providers: xref:Microsoft.AspNetCore.Localization.QueryStringRequestCultureProvider, xref:Microsoft.AspNetCore.Localization.CookieRequestCultureProvider, and xref:Microsoft.AspNetCore.Localization.AcceptLanguageHeaderRequestCultureProvider. Use RequestLocalizationOptions.RequestCultureProviders property to change the order of these providers as shown in the following below:
app.UseRequestLocalization(options =>
{
var questStringCultureProvider = options.RequestCultureProviders[0];
options.RequestCultureProviders.RemoveAt(0);
options.RequestCultureProviders.Insert(1, questStringCultureProvider);
});
In the preceding example, the order of QueryStringRequestCultureProvider and CookieRequestCultureProvider is switched, so the RequestLocalizationMiddleware looks for the cultures from the cookies first, then the query string.
As previously mentioned, add a custom provider via xref:Microsoft.AspNetCore.Builder.RequestLocalizationOptionsExtensions.AddInitialRequestCultureProvider%2A which sets the order to 0, so this provider takes the precedence over the others.
The RequestLocalizationOptions.CultureInfoUseUserOverride property allows the app to decide whether or not to use non-default Windows settings for the xref:System.Globalization.CultureInfo xref:System.Globalization.CultureInfo.DateTimeFormat and xref:System.Globalization.CultureInfo.NumberFormat properties. This has no impact on Linux. This directly corresponds to xref:System.Globalization.CultureInfo.UseUserOverride.
app.UseRequestLocalization(options =>
{
options.CultureInfoUseUserOverride = false;
});
This sample Localization.StarterWeb project on GitHub contains UI to set the Culture. The Views/Shared/_SelectLanguagePartial.cshtml file allows you to select the culture from the list of supported cultures:
The Views/Shared/_SelectLanguagePartial.cshtml file is added to the footer section of the layout file so it will be available to all views:
The SetLanguage method sets the culture cookie.
You can't plug in the _SelectLanguagePartial.cshtml to sample code for this project. The Localization.StarterWeb project on GitHub has code to flow the RequestLocalizationOptions to a Razor partial through the Dependency Injection container.
See Globalization behavior of model binding route data and query strings.
Localizing an app also involves the following tasks:
:::moniker-end
[!INCLUDE select-language-culture67] [!INCLUDE select-language-culture5]