ForEvolve.AspNetCore.Localization
The ForEvolve.AspNetCore.Localization package allows you to enable localization of Asp.Net Core 2.0 applications in a few line of code.
This is very useful for ValidationAttributes
like [Required]
. No need to specify any string or error message, ForEvolve.AspNetCore.Localization
do it for you.
ForEvolve NuGet V3 feed URL packages source. See the Table of content project for more info.
Supported languages:
English
French
Supported attributes
- CompareAttribute
- EmailAddressAttribute
- RequiredAttribute
- CreditCardAttribute
- FileExtensionsAttribute
- MaxLengthAttribute
- MinLengthAttribute
- PhoneAttribute
- RangeAttribute
- RegularExpressionAttribute
- UrlAttribute
- StringLengthAttribute (see StringLengthLocalizationValidationAttributeAdapter.cs)
See ForEvolveMvcDefaultLocalizationAdapterOptions.cs for the list of supported attributes used by the DefaultLocalizationValidationAttributeAdapter
.
You can also create and register your own adapters and attributes.
How to use
To enable localization for everything, including data annotation, you need to:
- Make sure your application is targetting
Asp.Net Core 2.0
- Add
ForEvolve.AspNetCore.Localization
NuGet package to your project (or theForEvolve
meta-package). - In
Startup.cs
add and configure dependencies (see below).
public void ConfigureServices(IServiceCollection services)
{
// Localization & options
services.AddForEvolveLocalization();
// ...
// MVC
services
.AddMvc()
.AddForEvolveMvcLocalization();
}
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
// Localization
app.UseForEvolveRequestLocalization();
//...
}
As you can see, it took only 3 lines of code to enable localization.
Code break down
services.AddForEvolveLocalization();
add all necessary services to the DI container, including supported resources, resource path, etc. This also calls services.AddLocalization(...)
for you, defining a default ResourcesPath
to "Resources"
. You can change the default (all defaults actually).
To configure the options, you can pass a second argument of type Action<ForEvolveLocalizationOptions>
to the services.AddForEvolveLocalization();
extension method.
To make it easy to use, I made sure that everything is configurable at a single place instead of spreading settings around.
Example 1:
services
.AddForEvolveLocalization(options => {
options.ResourcesPath = "new/place/where/to/store/resources";
});
Example 2:
services
.AddForEvolveLocalization(options => {
options.ResourcesPath = "new/place/where/to/store/resources";
options.MvcOptions.EnableViewLocalization = false;
options.MvcOptions.ConfigureValidationMetadataProvider = (provider) =>
{
provider.Adapters.Add(new SomeCoolAdapterThatICreatedOnlyForMyProject());
};
});
The IMvcBuilder.AddForEvolveMvcLocalization();
extension method register the ILocalizationValidationMetadataProvider
(this does the validation attribute localization magic) as well as AddViewLocalization()
and AddDataAnnotationsLocalization()
.
You can opt-out by setting options.MvcOptions.EnableViewLocalization
or options.MvcOptions.EnableDataAnnotationsLocalization
to false
(in the call to services.AddForEvolveLocalization();
).
The IApplicationBuilder.UseForEvolveRequestLocalization()
extension method calls app.UseRequestLocalization()
with some options. Once again all parameters are updatable in the initial call to services.AddForEvolveLocalization();
.
How to contribute a translation
Since I only know French and English, I can't translate messages into more languages, so contributions are very welcome.
How to submit a new translation:
- Fork the repo
- Create a resource file for the language you want to translate error messages into.
- Translate it (obviously)
- Open a pull request
Since I don't speak all languages, I cannot validate those that I don't know (except maybe by using Google Translate), so it's up to you to makes things right! (or PR corrections)
I will do my best to integrates PR as fast as possible.
Where are the error messages located?
If you look under src/ForEvolve.AspNetCore.Localization/Resources/
, you will find DataAnnotationSharedResource.resx
and DataAnnotationSharedResource.{lang}.resx
files.
You can copy any one of those and translate the values.
If you want to create a culture-specific translation, example: fr-CA
, please make sure that there is an fr
translation (neutral culture) first which will be the default for that language.
Example:
- First we need a
DataAnnotationSharedResource.fr.resx
file (already there). - Then we could add
DataAnnotationSharedResource.fr-CA.resx
,DataAnnotationSharedResource.fr-FR.resx
, etc.
Error messages
I modified default error messages a little to make them more linear. Sometimes it was written The field {0} ...
and sometimes it was The {0} field ...
. I decided to normalize messages to The {0} field ...
.
I am open to suggestion if you think this makes no sense. English is only my secondary language.
Error messages source (if you want the original error messages): corefx/src/System.ComponentModel.Annotations/src/Resources/Strings.resx
The plan
Before looking to the future let's look at the history of the project.
The history of the project
I created this project because I did not want to code something similar to this every single time I start a new Asp.Net Core application. I did not want to write an error message on every ValidationAttribute either (which seems to be the official solution).
To be honest, I was a little disappointed to see how hard it is to localize Asp.Net Core validation attributes. This should be trivial.
I don't want to criticize the design made by the team that built that without knowing, so I will assume there are some good reasons behind these design choices (technical or not).
That said, the other parts of the localization pipeline of Asp.Net Core are pretty neat with IStringLocalizer
, IHtmlLocalizer
and IViewLocalizer
.
The future
I plan on using this library for multiple projects so it should evolve in the future. If you have ideas, requests or find bugs, feel free to open issues or submit PRs.
If you want to contributes some code, other than translating error messages, feel free to contact me.
To conclude, I hope this is only the beginning of the project.
For example, I'd like, at some point, to extract the resources somewhere else, maybe use some other resource provider like a database or JSON files...