AspNetCore.Docs/aspnetcore/fundamentals/localization-extensibility.md

title	author	description	monikerRange	ms.author	ms.custom	ms.date	no-loc	uid
Localization Extensibility	hishamco	Learn how to extend the localization APIs in ASP.NET Core apps.	>= aspnetcore-2.1	riande	mvc	08/03/2019	Kestrel appsettings.json ASP.NET Core Identity cookie Cookie Blazor Blazor Server Blazor WebAssembly Identity Let's Encrypt Razor SignalR	fundamentals/localization-extensibility

Localization Extensibility

By Hisham Bin Ateya

This article:

• Lists the extensibility points on the localization APIs.
• Provides instructions on how to extend ASP.NET Core app localization.

Extensible Points in Localization APIs

ASP.NET Core localization APIs are built to be extensible. Extensibility allows developers to customize the localization according to their needs. For instance, OrchardCore has a POStringLocalizer. POStringLocalizer describes in detail using Portable Object localization to use PO files to store localization resources.

This article lists the two main extensibility points that localization APIs provide:

• xref:Microsoft.AspNetCore.Localization.RequestCultureProvider
• xref:Microsoft.Extensions.Localization.IStringLocalizer

Localization Culture Providers

ASP.NET Core localization APIs have four default providers that can determine the current culture of an executing request:

• xref:Microsoft.AspNetCore.Localization.QueryStringRequestCultureProvider
• xref:Microsoft.AspNetCore.Localization.CookieRequestCultureProvider
• xref:Microsoft.AspNetCore.Localization.AcceptLanguageHeaderRequestCultureProvider
• xref:Microsoft.AspNetCore.Localization.CustomRequestCultureProvider

The preceding providers are described in detail in the Localization Middleware documentation. If the default providers don't meet your needs, build a custom provider using one of the following approaches:

Use CustomRequestCultureProvider

xref:Microsoft.AspNetCore.Localization.CustomRequestCultureProvider provides a custom xref:Microsoft.AspNetCore.Localization.RequestCultureProvider that uses a simple delegate to determine the current localization culture:

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

options.RequestCultureProviders.Insert(0, new CustomRequestCultureProvider(async context =>
{
    var currentCulture = "en";
    var segments = context.Request.Path.Value.Split(new char[] { '/' }, 
        StringSplitOptions.RemoveEmptyEntries);

    if (segments.Length > 1 && segments[0].Length == 2)
    {
        currentCulture = segments[0];
    }

    var requestCulture = new ProviderCultureResult(currentCulture);
    
    return Task.FromResult(requestCulture);
}));

::: moniker-end

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

options.AddInitialRequestCultureProvider(new CustomRequestCultureProvider(async context =>
{
    var currentCulture = "en";
    var segments = context.Request.Path.Value.Split(new char[] { '/' }, 
        StringSplitOptions.RemoveEmptyEntries);

    if (segments.Length > 1 && segments[0].Length == 2)
    {
        currentCulture = segments[0];
    }

    var requestCulture = new ProviderCultureResult(currentCulture);
    
    return Task.FromResult(requestCulture);
}));

::: moniker-end

Use a new implemetation of RequestCultureProvider

A new implementation of xref:Microsoft.AspNetCore.Localization.RequestCultureProvider can be created that determines the request culture information from a custom source. For example, the custom source can be a configuration file or database.

The following example shows AppSettingsRequestCultureProvider, which extends the xref:Microsoft.AspNetCore.Localization.RequestCultureProvider to determine the request culture information from appsettings.json:

public class AppSettingsRequestCultureProvider : RequestCultureProvider
{
    public string CultureKey { get; set; } = "culture";

    public string UICultureKey { get; set; } = "ui-culture";

    public override Task<ProviderCultureResult> DetermineProviderCultureResult(HttpContext httpContext)
    {
        if (httpContext == null)
        {
            throw new ArgumentNullException();
        }

        var configuration = httpContext.RequestServices.GetService<IConfigurationRoot>();
        var culture = configuration[CultureKey];
        var uiCulture = configuration[UICultureKey];

        if (culture == null && uiCulture == null)
        {
            return Task.FromResult((ProviderCultureResult)null);
        }

        if (culture != null && uiCulture == null)
        {
            uiCulture = culture;
        }

        if (culture == null && uiCulture != null)
        {
            culture = uiCulture;
        }
        
        var providerResultCulture = new ProviderCultureResult(culture, uiCulture);

        return Task.FromResult(providerResultCulture);
    }
}

Localization resources

ASP.NET Core localization provides xref:Microsoft.Extensions.Localization.ResourceManagerStringLocalizer. xref:Microsoft.Extensions.Localization.ResourceManagerStringLocalizer is an implementation of xref:Microsoft.Extensions.Localization.IStringLocalizer that is uses resx to store localization resources.

You aren't limited to using resx files. By implementing IStringLocalizer, any data source can be used.

The following example projects implement xref:Microsoft.Extensions.Localization.IStringLocalizer:

• EFStringLocalizer
• JsonStringLocalizer
• SqlLocalizer