Server-side resource integration

This article describes how to integrate server-side resources into a ASP.NET Core application.

Server-Side Resource Initialization
To enable server-side resource retrieval, you must enable the ResourceHostedService service in the application startup configuration. This service will take care of loading all the resources from the backend and storing them in an in-memory dictionary.

// Startup.cs
services.AddHostedService<ResourceHostedService>();

The ResourceHostedService populates the CachedResources key-value dictionary, which is present in the LocalizationService singleton service. After resources have been loaded into memory, the storage is no longer queried, unless a new manual initialization from the backend.

Configuring Location Options

To disable resource loading at startup, you can edit the appsettings.json file:

// Appsettings.json "AppSettings":
{ 
	"Localization": { 
		"IsResourceInitDisabled": false
 	} 
}

If the IsResourceInitDisabled option is set to true, resources won't load when the app is launched.

Configuring Data Annotations
You must configure ASP.NET MVC Core to use localized resources in data annotations, such as model validations.

// Startup.cs
IMvcBuilder builder = services.AddControllersWithViews()
	.AddDataAnnotationsLocalization(options => 
	{ 
		options.DataAnnotationLocalizerProvider = (type, localizerFactory) => { return localizerFactory.Create(type); }; 
	});

At this point, the localized resources will be available in all server-side classes through the LocalizationService and Localizer.

Localizer

Localizer is a class that extends the native IStringLocalizer class of ASP.NET MVC Core, customizing resource retrieval methods. This class allows you to obtain localized strings and interpolate values.

Example of use:

public class HomeController(IStringLocalizer localizer) : Controller
{
   public async Task<IActionResult> Home(CancellationToken cancellationToken)
   {
       var value = localizer["App.Header.Hello"];
       return View();
   }
}

Value interpolation

Localizer supports interpolating values in resources using the usual {} curly placeholders.

Example:

var value = localizer["App.Header.WelcomeUser", "Roby", "Consoli"];
// Output: "Welcome Roby Consoli!"

Management of cultures
The current culture value is automatically retrieved from HttpContext.Items["Culture"]. However, you can retrieve a resource in a specific culture by using a dedicated localizer:

var localizerIT = ((Localizer)localizer).WithCulture("it-IT");
var valueIT = localizerIT["App.Header.WelcomeUser", "Roby", "Consoli"];
// Output: "Benvenuto Roby Consoli!"

Using Localizer in Razor Views

To use Localizer in Razor views, you need to add the class in the _ViewImports.cshtml file:

// _ViewImports.cshtml
@inject IStringLocalizer localizer

And then use it in the views:

<div>@localizer["App.Header.Hello"]</div>

Fallback Cultures

Localizer allows you to use a fallback culture when the value of the resource is not available in the current culture. The fallback culture can be configured in the appsettings.json file:

"AppSettings": {
   "Localization": {
     "FallbackCultures": [
       {
         "Culture": "zh-Hans",
         "Fallback": "it-IT"
       },
       {
         "Culture": "default",
         "Fallback": "en-US"
       }
     ]
   }
 }

If the resource is not available in the current culture, the system will attempt to retrieve the resource in the specified fallback culture. If that culture doesn't have it either, the default fallback culture (en-US in this example) will be used.