Internationalization In ASP.NET Core MVC

Introduction

 

Internationalization describes both, Globalization and Localization.

 

 

Globalization is a process of supporting different cultures. Globalization allows us to create multilingual web sites with ASP.NET Core. It adds support the display of input and output of a defined language that is related to specific geographic areas. It involves identifying the culture and writing code that functions equally to any supported culture.

 

We can have an application which supports multiple cultures and culture preferences can be selected from different sources such a browser's preferred language. Our application displays the data in the selected language.

 

The localization process includes translating the UI of the application for the specific culture. In other term, it is the process of adapting a globalized application that we already processed for localization for specific cultures.

 

To describe how to do globalization and localization with ASP.NET Core MVC, I have created a Web application.

 

The next step is to add localization support in startup class. In the ConfigureSevices method of startup class, I have added localization options such as path of resource files. In this method, I have also configured requested localization option. In this option, I have added supported cultures and default culture for request.

 

Startup.cs

public void ConfigureServices(IServiceCollection services)
{
    // Add framework services.
    services.AddApplicationInsightsTelemetry(Configuration);
    services.AddLocalization(options => options.ResourcesPath = "Resources");

    services.Configure<RequestLocalizationOptions>(options =>
    {
        var supportedCultures = new[]
        {
                new CultureInfo("en-US"),
                new CultureInfo("de-DE")
        };

        options.DefaultRequestCulture = new RequestCulture(culture: "en-US", uiCulture: "en-US");
        options.SupportedCultures = supportedCultures;
        options.SupportedUICultures = supportedCultures;
    });

    services.AddMvc();
}

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
    loggerFactory.AddConsole(Configuration.GetSection("Logging"));
    loggerFactory.AddDebug();

    var localizationOption = app.ApplicationServices.GetService<IOptions<RequestLocalizationOptions>>();
    app.UseRequestLocalization(localizationOption.Value);

    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
        app.UseBrowserLink();
    }
    else
    {
        app.UseExceptionHandler("/Home/Error");
    }

    app.UseStaticFiles();

    app.UseMvc(routes =>
    {
        routes.MapRoute(
            name: "default",
            template: "{controller=Home}/{action=Index}/{id?}");
    });
}

The next step is to add resource folder and resource file in it. For demo purposes, I have added two resource files: one for English and another one for German.

 

 

This resources folder must contain the resources file in specific folder structure or file name otherwise it will not work as expected. ASP.NET Core introduces two interfaces: IStringLocalizer and IStringLocalizer<T>. These interfaces help us to improve productivity when developing localized application. The IStringLocalizer interface use Resource manager and resource reader to provide culture specific resources at run-time. It has IEnumerable and indexer to return the specific string.

 

The IStringLocalizer<T> implementation comes from Dependency Injection (DI) where T is our controller class Type. The indexer of this interface returns key if it is not found in resource file or resource file is not found. Our controller code look like as following.

 

HomeController.cs

public class HomeController : Controller
{
    private readonly IStringLocalizer<HomeController> _localizer;
    public HomeController(IStringLocalizer<HomeController> localizer)
    {
        _localizer = localizer;
    }
    public IActionResult Index()
    {
        ViewData["Message"] = _localizer["Test String"];
        return View();
    }
}

Here To verify resource string, I am displaying it on view by using following code.

 

Index.cshtml

<div class="col-md-11">
    <h2>Localization Test</h2>
    <br />
    <br />
    <h3>@ViewData["Message"]</h3>
</div>

The IStringLocalizer<T> will find the provided string based on the current culture and controller type i.e. HomeController in this case. Currently, we are using en-US culture, then the localizer will look for the either of files: Resources/ Controllers.HomeController.en-US.resx or Resources/ Controllers/HomeController.en-US.resx. If the file exists, localizer tries to find the key from the resource file. If key is not found from resource file key itself will be used as the resource and return.

 

 

Now I am running my application. But as a result, it show me resource key instead of resource value.

 

Output 

 

 

To resolve this issue, we need to add reference of "Localization.AspNetCore.TagHelpers" in our project. This tag helper helps us to make working with localized content. We can add the reference either by using nuget package or we can add reference in .csproj file and download referent using "dotnet restore" command.

 

.csproj file

<ItemGroup>
    <PackageReference Include="Localization.AspNetCore.TagHelpers" Version="0.3.0" />
…
…
</ItemGroup>

Now I am re-running the application and found it working as expected.

 

Output 

 

Now I am adding a new resource file for German language (de-DE) and adding the same key as the English resource file. To test application on German language, I am changing the language from browser and re-run my application.

 

 

Change the language from the browser in windows 10 

 

 

Output 

 

View localization

 

The interface IViewLocalizer service provides localized string for view. A ViewLocalizer class implements this interface and finds the resource location from the view file path. The behavior of this localizer is the same as controller localizer described above i.e. if key is not find in resource file, it's return key.

 

To demonstrate the concept, I have created view and resources file. The IViewLocalizer use the name of the view file to find the associated resources. For this example, I have added view resource for about.cshtml view, so the resource file will look like Resources/Views.Home.About.en-US.resx or Resources/Views/Home/About.en-US.resx. This interface is used in a similar way as IStringLocalizer<T> is used to find resource key.

 

About.cshtml

@using Microsoft.AspNetCore.Mvc.Localization

@inject IViewLocalizer Localizer

<h3>@Localizer["HelloFriends"]</h3>

When I run this page, it throws the error and says “InvalidOperationException: No service for type 'Microsoft.AspNetCore.Mvc.Localization.IViewLocalizer' has been registered.”

 

 

 

This error is due to the fact that we have not registered the service for view localization. To resolve the error, we need to register “AddViewLocalization” service in ConfigureServices method of startup class.

 

Startup.cs 

public void ConfigureServices(IServiceCollection services)
{
…
…
    services.AddMvc().AddViewLocalization(LanguageViewLocationExpanderFormat.Suffix);
…
…
}

 

DataAnnotations localization

 

DataAnnotation error messages are localized with the interface IStringLocalizer<T>. We can set resource file path using Option.ResourcePath property and error messages can be stored either paths Resources/ViewModels.Home.MyViewModel.en-US.resx or Resources/ViewModels/Home/MyViewModel.en-US.resx

 

We need to register data annotation localization service in ConfigureServices method of Startup class.

 

Startup.cs

public void ConfigureServices(IServiceCollection services)
{
…
…

services.AddMvc()
       .AddViewLocalization(LanguageViewLocationExpanderFormat.Suffix)
       .AddDataAnnotationsLocalization();
…
…
}

In this example, I have created a model and defined one property and property decorated with “Required” and “DisplayName” data annotation attribute. With Required attribute, I am passing resource key instead of the error message and same as for DisplayName attribute.

 

MyViewModel.cs

using System.ComponentModel.DataAnnotations;

namespace demoApp.ViewModels.Home
{
    public class MyViewModel
    {
        [Required(ErrorMessage = "RequiredName")]
        [Display(Name = "Name")]
        public string Name { get; set; }
    }
}

Contact.cshtml

@model demoApp.ViewModels.Home.MyViewModel
@using Microsoft.AspNetCore.Mvc.Localization

<form action="/Home/Save" method="post">
    @Html.LabelFor(model => model.Name)
    <br />
    @Html.EditorFor(model => model.Name)
    @Html.ValidationMessageFor(model => model.Name)

    <br />
    <br />
    <input type="submit" value="Save" class="btn btn-default" />
</form>

Resource file for English language

 

Ouput 



Resource file naming

 

Resource files are named for full type of their class except assembly name. For example English resource in our project which main assembly is "demoApp.dll" and if we are creating for class "demoApp.Controllers.HomeController" then the resource file name become "Controllers.HomeController.en-Us.resx". In the ConfigureServices method we need to set resource file path. If we did not set the ResourcePath property, System will looks .resx files in project base directory.

 

Alternatively we can use folders to organize resource files. For the above explain example, the path would be "Resources/Controllers/HomeController.en-US.resx".

 

Resource file name for Razor views follow very similar pattern. It is either dot naming or path naming. Razor view resource files has similar path of their associated view. For example English resource file name for view Views/Home/Index.cshtml is either Resources/Views/Home/Index.resx or Resources/Views.Ho,e.Index.resx. If we are not defining the ResourcePath property, resource file would be located in same folder as view.

 

Summary

 

Internationalization involves Localization and Globalization. Both are critical aspects of many web applications.

 

Internationalization is abbreviated to "I18N". The abbreviation takes first and last character and number of characters between them. Here there are 18 characters between "I" and "N" character. Same things is applied to Localization (L10N) and Globalization (G11N).

• Globalization (G11N) - It is the process of making an application support different languages and regions.
• Localization (L10N) - The process of customizing an application for a given language and region.
• Internationalization (I18N) - Describes both globalization and localization.