Let’s get started.<\/p>\n
The Difference Between Globalization and Localization<\/h2>\n
Globalization and Localization are two very closely related terms, so let’s define and understand them.\u00a0<\/p>\n
Globalization is the process of designing applications to support different languages and cultures.<\/strong><\/p>\n Localization, on the other hand, is the process of adjusting an application for a specific language\/culture.<\/strong><\/p>\n With these definitions in mind, let’s look at how we can design our applications for<\/strong>\u00a0globalization<\/strong> by introducing<\/strong>\u00a0localization<\/strong> for specific cultures.<\/p>\n We’ll start by creating an MVC application. This will allow us to look at the various ways we can localize our applications and serve content based on the user’s locale. Let’s open a command terminal and run Resource files are a specific file format ( By convention, resource files should be separated into a separate folder called\u00a0 We can either organize the files into separate folders, such as For our application, we will follow the folder hierarchy for organizing our resource files. With that in mind, let’s create 2 resource files for the To start, let’s create a Now, we add a file called Let’s open the We’ll do the same for the Spanish resource file, making sure to use the same name:<\/p>\n Before we can test out the localization of the application, we need to configure our application to register the required services. In the We need to set the Also, we can configure the supported cultures for our application:<\/p>\n Here, we define our default culture ( Finally, we need to tell our application to use these supported cultures:<\/p>\n With our resource files defined and our application configured for localization, let’s look at how we can use them in our application.<\/p>\n ASP.NET Core provides us with an easy-to-use interface for making our applications localized, Let’s look at how to use this interface in our application.<\/p>\n Now that we have our resource files created, let’s create the accompanying controller:<\/p>\n We start by injecting the In the Finally, we return to our view, which we’ll create next.<\/p>\n In the Views folder, let’s create a new folder called Here, we simply access the\u00a0 If we run our application and navigate to Let’s look at a couple of different methods for changing the culture so we can test whether our localization is working correctly.<\/p>\n We can manually specify the culture we wish to use by using the Let’s try it out. If we navigate to the Localization controller and pass the The Accept-Language<\/a> header is another method for specifying the locale the user wishes to use. This is set at a browser level and allows users to set multiple languages, which are weighted based on a quality value from 0-1, letting the browser know which language the user would prefer to use.<\/p>\n What happens if we had some HTML markup in our resource files? Well, if we continued to use the This is not desirable. Fortunately, ASP.NET provides us with a way to render HTML in our resource files correctly, using the Let’s change our resource\u00a0files to display our greeting as an We need to apply this change to both the English and Spanish resource files.<\/p>\n Now, in our To use the This time when we navigate to Instead of localizing at the controller level, we may wish to do so at the View level, which we can do with the Let’s create a new view to demonstrate using the Here, we inject the Next, we need to create new resource files, matching the name and location of this new view. Let’s create an English and Spanish resource file under the In the English file, we’ll add the Running our application and navigating to When we make use of ModelState validation<\/a> in our applications, we can provide error messages whenever a given input does not meet the property requirements. Fortunately, the ASP.NET Core Localization package accounts for this and allows us to configure localization for our error messages from the Let’s create a model with some data annotations in the Models folder:<\/p>\n Next, we’ll create the Spanish resource file for translating the error messages. In a new folder, As English is the default language we used when creating the error messages, we don’t need to create an English-specific resource file.<\/p>\n Now we must create the View that will display the Here, we create a simple form that is bound to our As we are using the Finally, we need to create the new endpoints that will return this new view:<\/p>\n The first endpoint is a simple Our second endpoint is a Now we are ready to test this out. If we navigate to To test out the Spanish version, let’s add the Entering some invalid values once again and submitting, we will see the Spanish variations of our error messages:<\/p>\n So far we have manually added the culture query parameter to determine the locale of the user. Let’s look at an alternative method using cookies.<\/p>\n We can store a user’s locale in a Cookie<\/a> which means we don’t have to pass it through the query parameter manually and allows us to set the culture programmatically. This would be the preferred method, as we can store the user’s locale between sessions, meaning they will return to the same locale each time.<\/p>\n Let’s start by creating a dropdown that we will add to our navigation bar to allow the user to select a language:<\/p>\n First, we inject Then, in the code block, we get these supported cultures to bind them to our dropdown. Also, we define a Finally, we add a form with our support languages dropdown that will submit to the We must remember to add this partial view to Now it’s time to add the controller that will set the culture in the cookie. We’ll start by creating a new We have a single Our cookie-based localization is now ready to test. If we run our application, we will see the dropdown on the navigation bar:<\/p>\nAdd Localization to an Application<\/h2>\n
dotnet new webapp -n Localization<\/code>, or we can also use Visual Studio to create a new project.<\/p>\nResource Files<\/h2>\n
.resx<\/code>) that allows us to define translations for any plaintext content we want to display in our application, in a key-value pair format. They allow us to separate the localized content from our code, meaning we can easily swap out different resource files for different languages without having to change our code.<\/p>\nFile Naming Convention<\/h3>\n
Resources<\/code>. When naming these files, they should follow the name of the class that will consume them, as well as include the language they represent.<\/p>\nResources\/Controllers\/LocalizationController.es.resx<\/code>, or leave them in the root Resources folder, ensuring to name them appropriately, in this case Resources\/Controllers.LocalizationController.es.resx<\/code>.<\/p>\nCreate Resource Files<\/h3>\n
LocalizationController<\/code> that we will create shortly. One will be in English and another in Spanish.<\/p>\nResources<\/code> folder, and in that, we’ll add another folder called Controllers<\/code>.<\/p>\nLocalizationController.en.resx<\/code>, and one called LocalizationController.es.resx<\/code>.<\/p>\nLocalizationController.en.resx<\/code> file first and add a new entry:<\/p>\n![\"localization](\"https:\/\/code-maze.com\/wp-content\/uploads\/2022\/10\/LocalizationController.en_.png\")
<\/a><\/p>\n![\"localization](\"https:\/\/code-maze.com\/wp-content\/uploads\/2022\/10\/LocalizationController.es_-1.png\")
<\/a><\/p>\nConfigure Supported Cultures<\/h2>\n
Program<\/code> class, let’s add localization to our application:<\/p>\nbuilder.Services.AddLocalization(options => options.ResourcesPath = \"Resources\");<\/code><\/p>\nResourcesPath<\/code> property to our Resources folder, so ASP.NET Core knows where to look for our resource files.<\/p>\nconst string defaultCulture = \"en-GB\";\r\n\r\nvar supportedCultures = new[]\r\n{\r\n new CultureInfo(defaultCulture),\r\n new CultureInfo(\"es\")\r\n};\r\n\r\nbuilder.Services.Configure<RequestLocalizationOptions>(options => {\r\n options.DefaultRequestCulture = new RequestCulture(defaultCulture);\r\n options.SupportedCultures = supportedCultures;\r\n options.SupportedUICultures = supportedCultures;\r\n});<\/pre>\nen-GB<\/code>) as well as another supported culture (es<\/code>).<\/p>\napp.UseRequestLocalization(app.Services.GetRequiredService<IOptions<RequestLocalizationOptions>>().Value);<\/code><\/p>\nIStringLocalizer Interface for Localization<\/h2>\n
IStringLocalizer<T><\/code>. This interface uses two classes, ResourceReader<\/code> and ResourceManager<\/code> which provides access to culture-specific resources at run-time. We can use dependency injection<\/a> to gain access to this interface to make the localization of our applications much more straightforward.<\/p>\nController Localization<\/h2>\n
public class LocalizationController : Controller\r\n{\r\n private readonly IStringLocalizer<LocalizationController> _localizer;\r\n\r\n public LocalizationController(IStringLocalizer<LocalizationController> localizer)\r\n {\r\n _localizer = localizer;\r\n }\r\n\r\n public IActionResult Index()\r\n {\r\n ViewData[\"Greeting\"] = _localizer[\"Greeting\"];\r\n return View();\r\n }\r\n}<\/pre>\nIStringLocalizer<LocalizationController><\/code> interface, which will give us access to our English and Spanish resource files.<\/p>\nIndex()<\/code> method, we set the ViewData<\/code> dictionary value for Greeting<\/code> from our resource file, which will be determined based on the culture of the user.\u00a0<\/p>\nLocalization<\/code> for our new controller, and create our Index view:<\/p>\n@{\r\n ViewData[\"Title\"] = \"IStringLocalizer\";\r\n}\r\n\r\n<div class=\"text-center\">\r\n <p>@ViewData[\"Greeting\"]<\/p>\r\n<\/div><\/pre>\nGreeting<\/code> key of the ViewData<\/code> dictionary.<\/p>\n\/Localization<\/code>, given that our culture is set to English, we will see the English variation of our Greeting<\/code> message.<\/p>\nRequest Culture with Query String<\/h3>\n
culture<\/code> query string parameter. By default in ASP.NET Core, the QueryStringRequestCultureProvider<\/code> is registered, allowing us to use this query string parameter in our application.<\/p>\nculture<\/code> query parameter with the value set to es<\/code>, we will see the Spanish variation of our greeting:<\/p>\n![\"culture](\"https:\/\/code-maze.com\/wp-content\/uploads\/2022\/10\/culture-query-param-2.png\")
<\/a><\/p>\nAccept-Language Request Header\u00a0<\/h3>\n
IHtmlLocalizer Interface for HTML Localization<\/h2>\n
IStringLocalizer<\/code> interface, we would see the HTML markup unrendered:<\/p>\n![\"raw-html-unrendered\"](\"http:\/\/drafts.code-maze.com\/wp-content\/uploads\/2022\/10\/raw-html-unrendered.png\")
<\/a><\/p>\nIHtmlLocalizer<\/code> interface.<\/p>\nh1<\/code>:<\/p>\n![\"html](\"https:\/\/code-maze.com\/wp-content\/uploads\/2022\/10\/h1-greeting.png\")
<\/a><\/p>\nLocalizationController<\/code>, instead of injecting IStringLocalizer<\/code>, we inject an IHtmlLocalizer<\/code>:<\/p>\npublic class LocalizationController : Controller\r\n{\r\n private readonly IHtmlLocalizer<LocalizationController> _localizer;\r\n\r\n public LocalizationController(IHtmlLocalizer<LocalizationController> localizer)\r\n {\r\n _localizer = localizer;\r\n }\r\n\r\n public IActionResult Index()\r\n {\r\n ViewData[\"Greeting\"] = _localizer[\"Greeting\"];\r\n return View();\r\n }\r\n}<\/pre>\nIHtmlLocalizer<\/code> interface, we need to register it in our Program<\/code> class:<\/p>\nbuilder.Services \r\n .AddControllersWithViews()\r\n .AddViewLocalization();<\/pre>\n
\/Localization<\/code> we will see our greeting rendered as an h1<\/code>.<\/p>\nView Localization With IViewLocalizer<\/h2>\n
IViewLocalizer<\/code> interface. We can choose to localize strings within the view, similar to how we’ve previously done, or localize the entire view, creating multiple variations for different languages.<\/p>\nIViewLocalizer<\/code> interface:<\/p>\n@using Microsoft.AspNetCore.Mvc.Localization\r\n\r\n@inject IViewLocalizer ViewLocalizer\r\n\r\n<div class=\"text-center\">\r\n <p>@ViewLocalizer[\"ViewGreeting\"]<\/p>\r\n<\/div><\/pre>\n
IViewLocalizer<\/code> interface from the Microsoft.AspNetCore.Mvc.Localization<\/code> namespace. Then we retrieve the ViewGreeting<\/code> value using the ViewLocalizer<\/code>, which will retrieve it from the required resource file.<\/p>\nResources\/Views\/Localization<\/code> folder, called LocalizedView.en.resx<\/code> and LocalizedView.es.resx<\/code> respectively.<\/p>\nViewGreeting<\/code> entry with a value of “Hello from a localized view!”<\/em>. In the Spanish file, we’ll add the same entry, using “\u00a1Hola desde una vista localizada!”<\/em> for the value.<\/p>\n\/Localization\/LocalizedView<\/code> we will see the English variation of our ViewGreeting<\/code> message. To test the Spanish variation, we can once again append the culture<\/code> query parameter with a value of es<\/code>.<\/p>\nLocalizing Error Messages With Data Annotations<\/h2>\n
Program<\/code> class:<\/p>\nbuilder.Services\r\n .AddControllersWithViews()\r\n .AddViewLocalization()\r\n .AddDataAnnotationsLocalization();<\/pre>\n
public class PersonViewModel\r\n{\r\n [Display(Name = \"FirstName\")]\r\n [Required(ErrorMessage = \"{0} is a required field\")]\r\n public string FirstName { get; set; }\r\n\r\n [Display(Name = \"LastName\")]\r\n [Required(ErrorMessage = \"{0} is a required field\")]\r\n public string LastName { get; set; }\r\n\r\n [Display(Name = \"Age\")]\r\n [Range(1, 100, ErrorMessage = \"{0} must be a number between {1} and {2}\")]\r\n public int Age { get; set; }\r\n}<\/pre>\nResources\/Models<\/code>, let’s create PersonViewModel.es.resx<\/code>:<\/p>\n![\"translating](\"https:\/\/code-maze.com\/wp-content\/uploads\/2022\/10\/personvm-spanish-resource-file.png\")
<\/a><\/p>\nPersonViewModel<\/code>:<\/p>\n@model PersonViewModel\r\n@{\r\n ViewData[\"Title\"] = \"Data Annotations\";\r\n}\r\n\r\n<div class=\"card\"> \r\n <div class=\"card-body\"> \r\n <form asp-action=\"DataAnnotationView\" asp-route-culture=@ViewData[\"culture\"]> \r\n <div class=\"row\"> \r\n <div class=\"col-md-6\"> \r\n <div class=\"form-group\"> \r\n <label asp-for=\"FirstName\" class=\"lable-control\"><\/label> \r\n <input asp-for=\"FirstName\" class=\"form-control\" \/> \r\n <span asp-validation-for=\"FirstName\" class=\"text-danger\"><\/span> \r\n <\/div> \r\n <\/div>\r\n <\/div>\r\n <div class=\"row\">\r\n <div class=\"col-md-6\">\r\n <div class=\"form-group\"> \r\n <label asp-for=\"LastName\" class=\"lable-control\"><\/label> \r\n <input asp-for=\"LastName\" class=\"form-control\" \/> \r\n <span asp-validation-for=\"LastName\" class=\"text-danger\"><\/span> \r\n <\/div> \r\n <\/div> \r\n <\/div>\r\n <div class=\"row\">\r\n <div class=\"col-md-6\">\r\n <div class=\"form-group\"> \r\n <label asp-for=\"Age\" class=\"lable-control\"><\/label> \r\n <input asp-for=\"Age\" class=\"form-control\" \/> \r\n <span asp-validation-for=\"Age\" class=\"text-danger\"><\/span> \r\n <\/div> \r\n <\/div> \r\n <\/div>\r\n <div class=\"form-group\"> \r\n <button type=\"submit\" class=\"btn btn-primary rounded-0 mt-2\">Submit<\/button> \r\n <\/div> \r\n <\/form> \r\n <\/div> \r\n<\/div><\/pre>\nPersonViewModel<\/code>, which will submit to an endpoint we will create next. We include a span<\/code> for each field with the asp-validation-for<\/code> attribute, which will display the error message we configured previously if the model is not valid.<\/p>\nculture<\/code> query parameter to determine the locale to use, we need to persist it in ViewData<\/code> so that we return the same locale after posting the form to the server. We pass this back to the server by defining the asp-route-culture<\/code> parameter on the form<\/code> element.<\/p>\npublic IActionResult DataAnnotationView([FromQuery] string? culture)\r\n{\r\n ViewData[\"culture\"] = culture;\r\n return View();\r\n}\r\n\r\n[HttpPost]\r\n[ValidateAntiForgeryToken]\r\npublic IActionResult DataAnnotationView(PersonViewModel personViewModel, [FromQuery] string? culture)\r\n{\r\n ViewData[\"culture\"] = culture;\r\n if (!ModelState.IsValid)\r\n {\r\n return View();\r\n }\r\n\r\n return View();\r\n}<\/pre>\nGET<\/code> endpoint. Here we add the culture value to ViewData<\/code>, so it can be sent in the form submission if present.<\/p>\nPOST<\/code> endpoint that will be used for form submission. Once again we pass the culture<\/code> parameter to ViewData<\/code>, and also check if the ModelState<\/code> is valid. In this instance, we simply return the view, which will display the error messages.<\/p>\nTest Data Annotation Localization<\/h3>\n
\/Localization\/DataAnnotationView<\/code>, enter some invalid fields and submit our form, we will see the default, English error messages:<\/p>\n![\"invalid](\"https:\/\/code-maze.com\/wp-content\/uploads\/2022\/10\/invalid-form-english-1.png\")
<\/a><\/p>\nculture<\/code> query parameter to our URL with the value of es<\/code>:<\/p>\n![\"empty](\"https:\/\/code-maze.com\/wp-content\/uploads\/2022\/10\/empty-form-spanish-1.png\")
<\/a><\/p>\n![\"invalid](\"https:\/\/code-maze.com\/wp-content\/uploads\/2022\/10\/invalid-form-spanish-1.png\")
<\/a><\/p>\nCookie-Based Localization Preferences<\/h2>\n
@using Microsoft.AspNetCore.Localization\r\n@using Microsoft.Extensions.Options\r\n\r\n@inject IOptions<RequestLocalizationOptions> LocalizationOptions\r\n\r\n@{\r\n var requestCulture = Context.Features.Get<IRequestCultureFeature>();\r\n\r\n var cultureItems = LocalizationOptions.Value.SupportedUICultures\r\n .Select(c => new SelectListItem { Value = c.Name, Text = c.Name })\r\n .ToList();\r\n\r\n var returnUrl = string.IsNullOrEmpty(Context.Request.Path) \r\n ? \"~\/\" \r\n : $\"~{Context.Request.Path.Value}{Context.Request.QueryString}\";\r\n}\r\n\r\n<div>\r\n <form asp-controller=\"Culture\" asp-action=\"SetCulture\" asp-route-returnUrl=\"@returnUrl\" \r\n class=\"form-horizontal nav-link text-dark\">\r\n <select name=\"culture\" \r\n onchange=\"this.form.submit();\" \r\n asp-for=\"@requestCulture.RequestCulture.UICulture.Name\" \r\n asp-items=\"cultureItems\">\r\n <\/select>\r\n <\/form>\r\n<\/div><\/pre>\nIOptions<RequestLocalizationOptions><\/code> which allows us to access the configured cultures for our application.<\/p>\nreturnUrl<\/code> route, so that whenever we change the language, we return to the same page the user was currently on, and not the default page.<\/p>\nSetCulture<\/code> method of the\u00a0Culture<\/code> controller, which we will define shortly.<\/p>\n_Layout.cshtml<\/code>:<\/p>\n<div class=\"navbar-collapse collapse d-sm-inline-flex justify-content-between\">\r\n <ul class=\"navbar-nav flex-grow-1\">\r\n <li class=\"nav-item\">\r\n @await Html.PartialAsync(\"_CulturePartial\")\r\n <\/li>\r\n <\/ul>\r\n<\/div><\/pre>\n
CultureController<\/code>, along with the single method required:<\/p>\npublic class CultureController : Controller\r\n{\r\n [HttpPost]\r\n public IActionResult SetCulture(string culture, string returnUrl)\r\n {\r\n Response.Cookies.Append(\r\n CookieRequestCultureProvider.DefaultCookieName,\r\n CookieRequestCultureProvider.MakeCookieValue(new RequestCulture(culture)),\r\n new CookieOptions { Expires = DateTimeOffset.UtcNow.AddDays(30) }\r\n );\r\n\r\n return LocalRedirect(returnUrl);\r\n }\r\n}<\/pre>\nPOST<\/code> method, SetCulture()<\/code> which is used from our dropdown when the value changes. In this method, we add a cookie to the Response<\/code> with the selected culture, setting the expiry time to 30 days in the future. Then, we redirect the user to the returnUrl<\/code>, which will be the URL they were currently on.<\/p>\nTest Cookie-Based Localization<\/h3>\n
![\"culture](\"https:\/\/code-maze.com\/wp-content\/uploads\/2022\/10\/culture-dropdown-1.png\")
<\/a><\/p>\n