Json Localizer library for .NetCore Asp.net projects
This library allows users to use JSON files instead of RESX in an ASP.NET application. The code tries to be most compliant with Microsoft guidelines. The library is compatible with NetCore.
An extension method is available for IServiceCollection
.
You can have a look at the method here
A set of options is available. You can define them like this :
services.AddJsonLocalization(options => {
options.CacheDuration = TimeSpan.FromMinutes(15);
options.ResourcesPath = "mypath";
options.FileEncoding = Encoding.GetEncoding("ISO-8859-1");
options.SupportedCultureInfos = new HashSet<CultureInfo>()
{
new CultureInfo("en-US"),
new CultureInfo("fr-FR")
};
});
$"{_env.WebRootPath}/Resources/"
_. Base path of your resources. The plugin will browse the folder and sub-folders and load all present JSON files.MissingTranslationLogBehavior = MissingTranslationLogBehavior.CollectToJSON
, defaults to MissingTranslations-<locale>.json
If UseBaseName is set to true, it will be searched for lingualization files by the following order - skipping the options below if any option before matches.
If you use a non-typed IStringLocalizer all files in the Resources-directory, including all subdirectories, will be used to find a localization. This can cause unpredictable behavior if the same key is used in multiple files.
If you use a typed localizer, the following applies - Namespace is the "short namespace" without the root namespace:
If you need a base shared files, just add a file named localization.shared.json in your ResourcesPath
In version 2.0.0, Pluralization was introduced. You are now able to manage a singular (left) and plural (right) version for the same Key. PluralSeparator is used as separator between the two strings.
For example : User|Users for key Users
To use plural string, use parameters from IStringLocalizer, if last parameters is a boolean, pluralization will be activated.
Pluralization is available with IStringLocalizer, IViewLocalizer and HtmlStringLocalizer :
In version 3.1.1 and above you can have multiple pluralization, to use it, you should
use IJsonStringLocalizer interface and this method LocalizedString GetPlural(string key, double count, params object[] arguments)
localizer.GetString("Users", true);
Version 2.2.0+ allows you to clean cache. It's usefull when you want's tu update in live some translations.
Example
public class HomeController{
private readonly IJsonStringLocalizer _localizer;
public HomeController(IJsonStringLocalizer<HomeController> localizer)
{
_localizer = localizer;
_localizer.ClearMemCache(new List<CultureInfo>()
{
new CultureInfo("en-US")
});
}
}
As you know, Blazor Server does not provide IHtmlLocalizer. To avoid this, you can now use
from IJsonStringLocalizer this method MarkupString GetHtmlBlazorString(string name, bool shouldTryDefaultCulture = true)
Platform Support
Platform | Version |
---|---|
NetCore | 7.0.0+ |
Blazor Server | 7.0.0+ |
Blazor Wasm | 7.0.0+ |
WithCulture method
WhithCulture method is not implemented and will not be implemented. ASP.NET Team, start to set this method Obsolete for version 3 and will be removed in version 4 of asp.net core.
For more information : https://github.com/AlexTeixeira/Askmethat-Aspnet-JsonLocalizer/issues/46
As asked on the request #64, Some user want to have the possiblities to manage file with i18n way. To answer this demand, a localization mode was introduced with default value Basic. Basic version means the the one describe in the previous parts
To use the i18n file management, use the the option Localization mode like this : cs LocalizationMode = LocalizationMode.I18n
.
After that, you should be able to use this json :
{
"Name": "Name",
"Color": "Color"
}
File name
File name are important for some purpose (Culture looking, parent culture, fallback).
Please use this pattern : [fileName].[culture].json If you need a fallback culture that target all culture, you can create a file named localisation.json. Of course, if this file does not exist, the chosen default culture is the fallback.
Important: In this mode, the UseBaseName options should be False.
For more information : https://github.com/AlexTeixeira/Askmethat-Aspnet-JsonLocalizer/issues/64
Because of the way Blazor Wasm works, the plugin will not be able to load files from the server. To avoid this, you should embed your files in the project and use the following code :
<EmbeddedResource Include="Resources\localization.json">
<CopyToOutputDirectory>Never</CopyToOutputDirectory>
</EmbeddedResource>
The second specificities is the management of the language files. Blazor Wasm uses the file path as Assembly name, so you can't have multiple files with the same name.
For example, if you have a file named localization.json in the folder Resources, you can't have another file starting with name localization in the folder Resources, a file with the name localization.fr.json will throw an exception.
So you should have different folder for each language culture.
After talking with others Devs about my package, they asked my about performance.
BenchmarkDotNet=v0.13.1, OS=Windows 10.0.22000
Intel Core i7-10870H CPU 2.20GHz, 1 CPU, 16 logical and 8 physical cores
.NET SDK=6.0.101
[Host] : .NET 6.0.1 (6.0.121.56705), X64 RyuJIT
DefaultJob : .NET 6.0.1 (6.0.121.56705), X64 RyuJIT
Method | Mean | Error | StdDev | Min | Max | Ratio | RatioSD | Gen 0 | Gen 1 | Gen 2 | Allocated |
---|---|---|---|---|---|---|---|---|---|---|---|
Localizer | 57.34 ns | 0.590 ns | 0.523 ns | 56.65 ns | 58.46 ns | 1.00 | 0.00 | - | - | - | - |
JsonLocalizer | 41.50 ns | 0.552 ns | 0.516 ns | 40.60 ns | 42.46 ns | 0.72 | 0.01 | 0.0057 | - | - | 48 B |
JsonLocalizerWithCreation | 169,174.60 ns | 1,070.840 ns | 1,001.664 ns | 167,445.80 ns | 170,873.85 ns | 2,950.03 | 33.21 | 4.6387 | 2.1973 | 0.2441 | 40,706 B |
I18nJsonLocalizerWithCreation | 228,438.65 ns | 4,188.350 ns | 6,643.166 ns | 218,070.12 ns | 245,103.20 ns | 4,026.62 | 130.32 | 12.2070 | 6.1035 | 0.4883 | 104,172 B |
JsonLocalizerWithCreationAndExternalMemoryCache | 2,813.26 ns | 51.894 ns | 48.541 ns | 2,731.36 ns | 2,920.27 ns | 49.04 | 0.92 | 0.5264 | 0.2632 | - | 4,424 B |
JsonLocalizerDefaultCultureValue | 145.34 ns | 1.284 ns | 1.201 ns | 142.61 ns | 146.81 ns | 2.53 | 0.04 | 0.0315 | - | - | 264 B |
LocalizerDefaultCultureValue | 159.06 ns | 0.919 ns | 0.859 ns | 157.63 ns | 160.51 ns | 2.77 | 0.03 | 0.0257 | - | - | 216 B |
Michael Monsour |
Luka Gospodnetic |
Christoph Sonntag |
Nacho |
Ashley Medway |
Serhii Voitovych |
James Hill |
Ferenc Czirok |
rohanreddyg |
rickszyr |
ErikApption |
A special thanks to @Compufreak345 for is hard work. He did a lot for this repo.
A special thanks to @EricApption for is work to improve the repo and making a very good stuff on migrating to net6 and System.Text.Json & making it working for blazor wasm