ASP.NET Core comes with new support for localization and globalization. I had to work with one specific prototyping scenario at work and as I was able to solve some problems that also other people may face I decided to share my knowledge and experience with my readers. This blog post is short overview of simple localization that uses some interesting tweaks and framework level dependency injection.
Source alert! Full sample solution built on ASP.NET Core 2.0 for this blog post is available at GitHub repository gpeipman/AspNetCoreLocalization.
My scenario was simple:
- We have limited number of supported languages and the number of languages doesn’t change often
- Coming of new language means changes in organization and it will probably be high level decision
- Although et-ee is official notation for localization here people are used with ee because it is our country domain
- Application has small amount of translations that are held in resource files (one per language)
As “ee” is not supported culture and “et” is not very familiar to regular users here I needed a way how to hide mapping from “ee” to “et” the way that I don’t have to inject this logic to views where translations are needed.
NB! To find out more about localization and globalization in ASP.NET Core please read the official documentation about it at https://docs.microsoft.com/en-us/aspnet/core/fundamentals/localization.
Setting up localization
Localization is different compared to previous versions of ASP.NET. We need some modifications to startup class. Let’s take ConfigureServices() method first.
public void ConfigureServices(IServiceCollection services)
{
services.AddLocalization();
services.AddMvc();
services.Configure<RouteOptions>(options =>
{
options.ConstraintMap.Add("lang", typeof(LanguageRouteConstraint));
});
// ...
services.AddSingleton<IHttpContextAccessor, HttpContextAccessor>();
}
You don’t have LanguageRouteConstraint class yet in your code. It’s coming later. Notice how supported cultures are configured and route based culture provider is added to request culture providers collection. These are important steps to make our site to support these cultures.
Now let’s modify Configure() method of startup class.
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
loggerFactory.AddConsole(Configuration.GetSection("Logging"));
loggerFactory.AddDebug();
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
app.UseBrowserLink();
}
else
{
app.UseExceptionHandler("/Home/Error");
}
app.UseStaticFiles();
var options = app.ApplicationServices.GetService<IOptions<RequestLocalizationOptions>>();
app.UseRequestLocalization(options.Value);
app.UseMvc(routes =>
{
routes.MapRoute(
name: "LocalizedDefault",
template: "{lang:lang}/{controller=Home}/{action=Index}/{id?}"
);
routes.MapRoute(
name: "default",
template: "{*catchall}",
defaults: new { controller = "Home", action = "RedirectToDefaultLanguage", lang = "et" });
});
}
Notice how localized route is defined. lang:lang means that there is request parameter lang that is validated by element with index “lang” from contraints map. Default route calles RedirectToDefaultLanguage() method of Home controller. We will take a look at this method later.
Now let’s add language route constraint to our web application project.
public class LanguageRouteConstraint : IRouteConstraint
{
public bool Match(HttpContext httpContext, IRouter route, string routeKey, RouteValueDictionary values, RouteDirection routeDirection)
{
if(!values.ContainsKey("lang"))
{
return false;
}
var lang = values["lang"].ToString();
return lang == "ee" || lang == "en" || lang == "ru";
}
}
This constraint checks if language route value is given and if it is then check is made if it has valid value. Note how I use here “ee” instead of “et”: it’s the route value from URL where I have to use “ee” instead of “et”.
Request localization pipeline
There’s one issue. Routes are defined when MVC is configured. When localization is configured there are no routes. If we configure localization later then MVC has no idea about it. To solve this puzzle we will use special pipeline class with MiddlewareFilterAttribute.
public class LocalizationPipeline
{
public void Configure(IApplicationBuilder app)
{
var supportedCultures = new List<CultureInfo>
{
new CultureInfo("et"),
new CultureInfo("en"),
new CultureInfo("ru"),
};
var options = new RequestLocalizationOptions()
{
DefaultRequestCulture = new RequestCulture(culture: "et", uiCulture: "et"),
SupportedCultures = supportedCultures,
SupportedUICultures = supportedCultures
};
options.RequestCultureProviders = new[] { new RouteDataRequestCultureProvider() { Options = options, RouteDataStringKey = "lang", UIRouteDataStringKey = "lang" } };
app.UseRequestLocalization(options);
}
}
To use pipeline class by middleware attribute we apply this attribute to controllers and view components where localization is needed.
[MiddlewareFilter(typeof(LocalizationPipeline))]
public class HomeController : Controller
{
// ...
}
Redirecting to language route
By default all requests to MVC that doesn’t have valid language in URL are handled by RedirectToDefaultLanguage() method of Home controller.
public ActionResult RedirectToDefaultLanguage()
{
var lang = CurrentLanguage;
if(lang == "et")
{
lang = "ee";
}
return RedirectToAction("Index", new { lang = lang });
}
private string CurrentLanguage
{
get
{
if(!string.IsNullOrEmpty(_currentLanguage))
{
return _currentLanguage;
}
if (string.IsNullOrEmpty(_currentLanguage))
{
var feature = HttpContext.Features.Get<IRequestCultureFeature>();
_currentLanguage = feature.RequestCulture.Culture.TwoLetterISOLanguageName.ToLower();
}
return _currentLanguage;
}
}
Here we have to replace “et” with “ee” to have a valid default URL. When on language route the CurrentLanguage property gives us current language from route. If it is not language route then language by culture is returned.
Building custom string localizer
As we have one resource file per language and as views are using in big part same translation strings we don’t go with resource file per view strategy. It would introduce many duplications and here we can avoid it by using just one StringLocalizer<T>. There reason why we need custom string localizer is the “ee” and “et” issue: “ee” is not known culture in .NET and we have to translate it to “et” to ask for resources.
public class CustomLocalizer : StringLocalizer<Strings>
{
private readonly IStringLocalizer _internalLocalizer;
public CustomLocalizer(IStringLocalizerFactory factory, IHttpContextAccessor httpContextAccessor) : base(factory)
{
CurrentLanguage = httpContextAccessor.HttpContext.GetRouteValue("lang") as string;
if(string.IsNullOrEmpty(CurrentLanguage) || CurrentLanguage == "ee")
{
CurrentLanguage = "et";
}
_internalLocalizer = WithCulture(new CultureInfo(CurrentLanguage));
}
public override LocalizedString this[string name, params object[] arguments]
{
get
{
return _internalLocalizer[name, arguments];
}
}
public override LocalizedString this[string name]
{
get
{
return _internalLocalizer[name];
}
}
public string CurrentLanguage { get; set; }
}
Our custom localizer is actually wrapper that translates “ee” and empty language to “et”. This way we have one localizer class to injeect to views that need localization. Base class StringLocalizer<T> gets Strings as type and this is the name of resource files.
Example of localized view
Now let’s take a look at view that uses custom localizer. It’s a simple view that outputs list of articles and below articles there is link to all news list, Link text is read from resource string called “AllNews”.
@model CategoryModel
@inject CustomLocalizer localizer
<section class="newsSection">
<header class="sectionHeader">
<h1>@Model.CategoryTitle</h1>
</header>
@Html.DisplayFor(m => m.CategoryContent, "ContentList")
<div class="sectionFooter">
<a href="@Url.Action("Category", new { id = Model.CategoryId })" class="readMoreLink">@localizer["AllNews"]</a>
</div>
</section>
Wrapping up
ASP.NET Core comes with new localization support and it is different from the one used in previous ASP.NET applications. It was easy to create language based URL-s and also handle the special case where local people are used with “ee” as language code instead of official code “et”. We were able to achieve decent language support for application where new languages are not added often. Also we were able to keep things easy and compact. We wrote custom string localizer class to handle mapping between “et” and “ee” and we wrote just some lines of code for it. And as it turned out we also got away with simple language route constraint. Our solution is good example how flexible ASP.NET Core is on supporting both small and big scenarios of lozalization.
References
- Globalization and localization (ASP.NET Core documentation)
- Url culture provider using middleware as filters in ASP.NET Core 1.1.0 (Andrew Lock)
- Plug ASP.NET Core Middlware in MVC Filters Pipeline (Hisham Bin Ateya)
View Comments (52)
Nice post, handles the problem gracefully.
This looks like similar to the approach I talked about in a series of posts, so nice to have some validation! :)
https://andrewlock.net/redirecting-unknown-cultures-to-the-default-culture-when-using-the-url-culture-provider/
Thanks for reference, Andrew! Your writing seems to help me to get closer to fully dynamic language support :)
Unless I'm mistaken, this won't work until you add a middleware to call app.UseRequestLocalization. This needs to be done by applying a MiddlewareFilterAttribute to the target controller(s).
The call is there in Configure() method above.
Nopes. That doesn't do.
This example has it: http://www.hishambinateya.com/plug-asp.net-core-middlware-in-mvc-filters-pipeline
And this too: https://andrewlock.net/url-culture-provider-using-middleware-as-mvc-filter-in-asp-net-core-1-1-0/
Got the point and made fixes. Things work way better on my prototype application now. Thanks, Ricardo! :)
No problem! Keep up the excellent work! ;-)
sorry but where is a _currentLanguage?
i start copy your code but...
can you write this article from a to z? thank you
_currentLanguage is class level variable in controller class.
please upload project...
this article is what i looking for, but i can't handle with it... if you can please upload a working project to look it, thank you
I have to create sample project for public space for this. I will do it but it doesn't happen very soon.
Could you share the sample project. Thank you very much.
I encounter this exception on CustomLocalizer:
InvalidOperationException: No service for type '{secret-namespace}.CustomLocalizer' has been registered.
And I'm not sure what can cause it.
I'm doubting that:
public class CustomLocalizer : StringLocalizer
IntelliSense suggested me 2 option for the Strings class:
Microsoft.VisualBasic and NuGet.Framework
I choosed the Microsoft one bacause seemed the most logical reason.
Do you have any insight? How do I register that service in the exception?
Can you add a guide portion about configuring the resource language files?
poor tutorial, you just post here then left forever.
Can you share your source code with me?
I really appreciate it.
I will build sample solution and publish it to GitHub. Hope to get it done for tomorrow.
Just finished sample solution. It is available in GitHub with full source code: https://github.com/gpeipman/AspNetCoreLocalization I built it on ASP.NET Core 2.0 but it should also work on 1.1.
Your sample solution works great. How to use CustomLocalizer in model data annotation. I would like to have a custom error message, for example:
[Required(ErrorMessage = "..."]
public string Email { get; set; }.
Thanks.
Here is the example of data annotations in ASP.NET Core: https://github.com/damienbod/AspNetCoreLocalization
Thanks for the great post! I have a question - it seems that current implementation allows to localize only small pieces of the view (e.g. @localizer["AllNews"]), but what if i want to return a completely different view for each language (Index.en-US.cshtml or Index.ru-RU.cshtml)? Do i need to deal view the view engine in this case?
It should be possible, yes. Try this in startup class of application:
public void ConfigureServices(IServiceCollection services)
{
// ...
services
.AddMvc()
.AddViewLocalization(LanguageViewLocationExpanderFormat.Suffix);
}
In views folders structure things like this:
Views
-- Home
---- en-us
------ Index.cshtml
------ About.cshtml
---- et-ee
------ Index.cshtml
------ About.cshtml
Thanks for this post. I just want to convert a MVC5 project to .NET CORE. We had custom culture resource files for each language and we map these files to the client based on URL.
for eg. http://localhost:50468/clienta/en [en-gb-clienta]
http://localhost:50468/clientb/en [en-gb-clientb]
In MVC5 we do mapping in a base Controller and the Application_Start pass ' ControllerBuilder.Current.SetControllerFactory(new DefaultControllerFactory(new BaseController()));'.
I think in above example I should do this 'CustomLocalizer' class.
Can you please advise me where is the best place to do mapping in .NET Core.
Thanks.
Hi - great example - what about if you want to have multi-lingual url slugs? So for English you might have ~/en/Home/About but in another language - e.g. Turkish - the url slugs should be the equivalent translation e.g. ~/tr/Anasayfa/Hakkımızda - but this should still route to the Home controller >> About action.
Thanks, Rich.
I don't have any ready-made solution to offer right now. One way to do it is to define route that takes all missed hits and figures out if it should render out something or return 404. I have to play with ASP.NET Core a little bit to find out how to do it.
What if i use Area?
for example in Identity area of ASP.NET Core that uses Pages instead of controllers?
anchors does not show lang in url (Identity/Account/Register).
When i open that link without lang TagHelper shows error that currentLanguage is null.
I am facing the same issue Identity pages does not show lang in the url (Identity/Account/XXX where xxx could be login, Register, passwordreset etc).
Is there a solution for this ?
Hi!
I'm trying to work out something for areas and identity. For Identity things are actually sad when it's used as Razor package. I have found no way to get any translations there. If Identity is scaffold then it's under our control but it's PITA to update it. Anyway I will comment here if I make some breakthrough.
Thanks Peipman, I appreciate it.
Here is a possibly nicer way to write that getter:
private string CurrentLanguage
{
get
{
var feature = HttpContext.Features.Get();
return feature.RequestCulture.Culture.TwoLetterISOLanguageName.ToLower();
}
}
is this works in asp.net2.2 version?
i tried it but i get this error:
NullReferenceException: Object reference not set to an instance of an object.
it seems localizer not finding words i view "@localizer["myword"]"
Hey. How to do default language to work without lang route parameter? / - default language, others with param as /ru, /it etc.
Hi Miri,
I'm sure it's possible and it takes just some small tweaks. When I think further then it can be also configuration option to not use language route with default language. I will update my sample solution to .NET Core 2.2 soon and I will comment here when it's done. Your wish will be also part of next version.
Great post. Waiting for asp.net Core 2.2 version!
Gunnar, thanks a lot for this code, it heped me a lot. Just an advice to add to article:
when you create a new application, the current version of visual studio 2019 creates a blank asp.net core 2.2 project with this setting
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2)
SetCompatibilityVersion completely breaks navigation, must be removed or it will not work at all.
Alberto, I have not yet ported this code over to .NET Core 2.2 and I cannot guarantee it works with it 100%. Once I get migration done I will write here.
ok thanks for the advice, hoping the my suggestion will help you with the port, then.
Another question, maybe it can be answered by anyone here:
service IOptions is registered as scoped? or singleton?
Just to know if it can be used to configure supported languages per user.
Hi ,
I Have six radio button on my page : English, Hindi ,Gujarati ,Marathi,Kannad and Urdu.
I want to when i am click on any radio button then as per click or name on radio button then same pages label is convert to selected language button.
For Ex : if i click on Hindi then page label is converted to Hindi.
I Want this solution in ASP.NET CORE.
Please help me out this problem.
Hi,
How do I add robots.txt and Sitemapindex in the root.
Eg: http://mydomain.com/robots.txt.
It's redirects to http://mydomain.com/ar/robots.txt, since 'ar' is the default lang?
Any suggestion please??
var lang = CurrentLanguage;
if(lang == "et")
{
lang = "ee";
}
return RedirectToAction("Index", new { lang = lang });
why not just:
return RedirectToAction("Index", new { lang = "ee" });
This is one speciality here. For culture settings we have to use et but people here are more used with ee as it matches country domain.
Hello Gunnar,
thank you for good code, i'm new in .net core and it really simple url rewrite working is good, but i have problem with localization it not worked for me, i need your help
An unhandled exception occurred while processing the request.
NullReferenceException: Object reference not set to an instance of an object.
buyitnow_pro.CustomLocalizer.get_Item(string name) in CustomLocalizer.cs, line 45
NullReferenceException: Object reference not set to an instance of an object.
buyitnow_pro.CustomLocalizer.get_Item(string name) in CustomLocalizer.cs
public override LocalizedString this[string name]
{
get
{
return _internalLocalizer[name];
}
}
AspNetCore.Views_Shared__Layout.b__44_8() in _Layout.cshtml
@localizer["Home"]
Microsoft.AspNetCore.Razor.Runtime.TagHelpers.TagHelperExecutionContext.SetOutputContentAsync()
AspNetCore.Views_Shared__Layout.b__44_1()
Microsoft.AspNetCore.Razor.Runtime.TagHelpers.TagHelperExecutionContext.SetOutputContentAsync()
AspNetCore.Views_Shared__Layout.ExecuteAsync()
Microsoft.AspNetCore.Mvc.Razor.RazorView.RenderPageCoreAsync(IRazorPage page, ViewContext context)
Microsoft.AspNetCore.Mvc.Razor.RazorView.RenderPageAsync(IRazorPage page, ViewContext context, bool invokeViewStarts)
Microsoft.AspNetCore.Mvc.Razor.RazorView.RenderLayoutAsync(ViewContext context, ViewBufferTextWriter bodyWriter)
Microsoft.AspNetCore.Mvc.Razor.RazorView.RenderAsync(ViewContext context)
Microsoft.AspNetCore.Mvc.ViewFeatures.ViewExecutor.ExecuteAsync(ViewContext viewContext, string contentType, Nullable statusCode)
Microsoft.AspNetCore.Mvc.ViewFeatures.ViewExecutor.ExecuteAsync(ActionContext actionContext, IView view, ViewDataDictionary viewData, ITempDataDictionary tempData, string contentType, Nullable statusCode)
Microsoft.AspNetCore.Mvc.ViewFeatures.ViewResultExecutor.ExecuteAsync(ActionContext context, ViewResult result)
Microsoft.AspNetCore.Mvc.ViewResult.ExecuteResultAsync(ActionContext context)
Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.InvokeResultAsync(IActionResult result)
Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.InvokeNextResultFilterAsync()
Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.Rethrow(ResultExecutedContext context)
Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.ResultNext(ref State next, ref Scope scope, ref object state, ref bool isCompleted)
Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.InvokeResultFilters()
Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.InvokeNextResourceFilter()
Microsoft.AspNetCore.Mvc.Internal.MiddlewareFilterBuilder+c+<b__8_0>d.MoveNext()
Microsoft.AspNetCore.Localization.RequestLocalizationMiddleware.Invoke(HttpContext context)
Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.InvokeNextResourceFilter()
Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.Rethrow(ResourceExecutedContext context)
Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.Next(ref State next, ref Scope scope, ref object state, ref bool isCompleted)
Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.InvokeFilterPipelineAsync()
Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.InvokeAsync()
Microsoft.AspNetCore.Builder.RouterMiddleware.Invoke(HttpContext httpContext)
Microsoft.AspNetCore.Localization.RequestLocalizationMiddleware.Invoke(HttpContext context)
Microsoft.AspNetCore.StaticFiles.StaticFileMiddleware.Invoke(HttpContext context)
Microsoft.AspNetCore.Diagnostics.DeveloperExceptionPageMiddleware.Invoke(HttpContext context)
Thank you!
Exception was thrown at line 45 in CustomLocalizer.cs. As I understand then some property on this line is null.
Put breakpoint to line 45 in CustomeLocalizer class, run your application in debug mode and check out what is actually null there.
First of all, I want to add a useful edit to your script, I use globalization and the url looks example.com/en-us
Your script has a limit of 2 characters of the language, and the first redirection triggers an error. For this, in your code, you can change the line in the routing
defaults: new { controller = "Home", action = "RedirectToDefaultLanguage", lang = "en" });
on
defaults: new { controller = "Home", action = "RedirectToDefaultLanguage", lang = "en-us" });
we will have an error but for everything to work correctly then in BaseController in private string CurrentLanguage need to replace the string
_currentLanguage = feature.RequestCulture.Culture.TwoLetterISOLanguageName.ToLower();
on
_currentLanguage = feature.RequestCulture.Culture.Name.ToLower();
Now I want to return to what happened to me, yes data is null, but i see value for CurrentLanguage is null too, i think i need find problem for CurrentLanguage value
CurrentLanguage null
_internalLocalizer null
But since for me it did not work initially as needed. I found another solution for localization.
in Startup.cs after namespase but before Startup class i'm add fake class GlobalSharedResource
public class GlobalSharedResource
{
}
this allows you to do the same thing as Common.en.resx
then i changed HomeController
[MiddlewareFilter(typeof(Helpers.LocalizationPipeline))]
public class HomeController : BaseController
{
private readonly IStringLocalizer _globallocalizer;
private readonly IStringLocalizer _globalLocalization;
public HomeController(IStringLocalizer globallocalizer, IStringLocalizer globalLocalization)
{
_globallocalizer = globallocalizer;
_globalLocalization = globalLocalization;
}
and so that it can be used directly in Views, I added next lines to the file
_ViewImports.cshtml
@using Microsoft.AspNetCore.Mvc.Localization
@inject IViewLocalizer Localizer
@inject IHtmlLocalizer globalLocalization
Thus Localizer["Title"] takes value from Controllers.HomeController.en.resx
globalLocalization as I indicated and the fake class is also called then I take values from GlobalSharedResource.en.resx
Handling of en and en-us correctly should be the matter of some existing or additional class that takes care of how cultures are named. In this means my solution is a little bit dirty because it leaks such details out to controllers. Trying to figure out what could be good and general enough solution.
Thank you for this tutorial but its not work correctly if you are using Areas With identity,
Did you find any solution for identity ??
I can not call Login Page with language in URL
I haven't touched ASP.NET Identity yet. AFAIK you have to scaffold Identity pages and views to make changes there (and when new version comes you have to repeat what you previously did). There's a blog post by Damien Bowden that might help you: https://damienbod.com/2018/07/03/adding-localization-to-the-asp-net-core-identity-pages/
hi
i can not this code in asp.net core 3.1 please again code for asp.net core 3.1 or .net 6
thanks you.