Walkthrough: Configuring localization and content translation

Version:

Important

If you integrated your ASP.NET Core app before September 2024, it's using the legacy ASP.NET Core Rendering SDK, version 22 or earlier. This SDK is no longer receiving updates, so we recommend that you upgrade to the latest version of the new ASP.NET Core SDK.

The Sitecore Rendering Engine SDK offers support for globalization and localization, the same as in ASP.NET Core.

For further information about globalization and localization, see the official Microsoft ASP.NET Core documentation.

Minimal configuration is required to add globalization and localization in a .NET Core rendering host application built using the Rendering Engine SDK. Most of this configuration is done in the Startup class of the rendering host application.

For further information about the Startup class, see the official Microsoft App startup in ASP.NET Core documentation.

This walkthrough describes how to:

Configure localization

You must first configure the Rendering Engine to use localization:

Add the following code to the Startup.cs class:

public void ConfigureServices(IServiceCollection services)
{
    services.AddLocalization(options => options.ResourcesPath = "Resources");

    services.AddSitecoreRenderingEngine(options =>
    {
        options.AddPartialView("Sample-Layout", "_SampleLayout")
               .AddDefaultPartialView("_ComponentNotFound");
    });
}

Configure the localization middleware

The current culture on a request is set in the localization middleware.

To configure the localization middleware:

In the Startup.cs class, in the Configure method, add callapp.UseRequestLocalization(options =>{}).

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseRouting();
    app.UseStaticFiles();
    app.UseRequestLocalization(options =>
    {
        var supportedCultures = new List<CultureInfo> { new CultureInfo("en"), new CultureInfo("da"), new CultureInfo("da-DK") };
        options.DefaultRequestCulture = new RequestCulture(culture: "da", uiCulture: "da");
        options.SupportedCultures = supportedCultures;
        options.SupportedUICultures = supportedCultures;
        options.UseSitecoreRequestLocalization();
    });
    app.UseSitecoreRenderingEngine();
}

Note

The UseSitecoreRequestLocalization() method allows culture to resolve from both the sc_lang query string and the culture token from route data (for example, en-us).

If you do not invoke the UseRequestLocalization method, the language specified in WithDefaultRequestOptions method is used instead.

In Startup.cs, in the app.UseEndpoints(endpoints =>{}) call in the Configure method, add the following to configure endpoints and add localized routes:
app.UseEndpoints(endpoints => { endpoints.AddLocalizedRoute("Localized", "Index", "Sitecore"); endpoints.MapFallbackToController("Index", "Sitecore"); });
The AddLocalizedRoute method accepts three parameters: the route name, default action, and controller name. It maps the controller route using the following pattern:
/{culture:culture}/{**sitecoreRoute}
If you want custom routing, you can find the culture and sitecoreRoute route values in the RouteValues collection of HttpRequest objects. See Routing in ASP.NET Core.

Configure method overview

The following is an example of the full Configure method in Startup.cs once you have configured the localization middleware:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseRouting();
    app.UseStaticFiles();
    app.UseRequestLocalization(options =>
    {
        var supportedCultures = new List<CultureInfo> { new CultureInfo("en"), new CultureInfo("da"), new CultureInfo("da-DK") };
        options.DefaultRequestCulture = new RequestCulture(culture: "da", uiCulture: "da");
        options.SupportedCultures = supportedCultures;
        options.SupportedUICultures = supportedCultures;
        options.UseSitecoreRequestLocalization();
    });
    app.UseSitecoreRenderingEngine();

    app.UseEndpoints(endpoints =>
    {
        endpoints.AddLocalizedRoute("Localized", "Index", "Sitecore");
        endpoints.MapFallbackToController("Index", "Sitecore");
    });
}

Note

See the getting started template for a working example of a rendering host with localization enabled.

If you have suggestions for improving this article, let us know!