AlexTeixeira / Askmethat-Aspnet-JsonLocalizer

Json Localizer library for .NetStandard and .NetCore Asp.net projects
MIT License
91 stars 29 forks source link
askmethat-aspnet-jsonlocalizer asp asp-net globalization json localization netcore netcore-asp netstandard nuget

Obsolete

This repository was moved to : AlexTeixeira/Askmethat-Aspnet-JsonLocalize

Askmethat-Aspnet-JsonLocalizer

Json Localizer library for .NetStandard and .NetCore Asp.net projects

Nuget

NuGet

Build

Build Status

Project

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 NetStandard & NetCore.

Configuration

An extension method is available for IServiceCollection. You can have a look at the method here

Options

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")
        };
    });

Current Options

Search patterns when UseBaseName = true

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.

Pluralization

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);

Clean Memory Cache

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")
      });
  }
}

Blazor Server HTML parsing

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)

Information

Platform Support

Version 3.2 and bellow

Platform Version
NetCore 3.0.0+
NetStandard 2.1.0+
Blazor Server 3.0.0+

Version 4 and above

Platform Version
NetCore 5.0.0+
NetStandard 2.1.0+
Blazor Server 5.0.0+
Blazor Wasm 5.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

Localization mode

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

I18n

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

Performances

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

Contributors

Michael Monsour
Michael Monsour
Luka Gospodnetic
Luka Gospodnetic
Christoph Sonntag
Christoph Sonntag
Nacho
Nacho
Ashley Medway
Ashley Medway
Serhii Voitovych
Serhii Voitovych
James Hill
James Hill
Ferenc Czirok
Ferenc Czirok
rohanreddyg
rohanreddyg
rickszyr
rickszyr
ErikApption
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

License

MIT Licence