AspNetCore.Localizer.Json

Json Localizer library for .NetCore Asp.net projects

Nuget

Build

Project

This library allows users to use JSON files instead of RESX in an ASP.NET application. It supports both embedded resources and physical files (choose via UseEmbeddedResources). The code tries to be most compliant with Microsoft guidelines. The library is compatible with .NET 8/9/10.

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")
        };
        options.AssemblyHelper = new AssemblyHelper("MyAssembly");
    });

Current Options (key ones)

• SupportedCultureInfos : cultures list (like RequestLocalizationOptions).
• ResourcesPath : base path of resources. For physical files, set a folder (e.g. i18n) and ensure files are copied to output.
• AdditionalResourcesPaths : extra folders (e.g. common_i18n).
• UseEmbeddedResources : default true. Set false to load JSON from disk.
• CacheDuration : memory cache duration (default 30 minutes).
• CacheMaxSize : max entries in serialized cache (LRU eviction).
• MaxMissingTranslations / MissingTranslationRetention : bounds + TTL for collected missing translations.
• FileEncoding : default UTF-8.
• LocalizationMode : Basic or I18n.
• PluralSeparator : default |.
• MissingTranslationLogBehavior : default LogConsoleError (or CollectToJSON).
• MissingTranslationsOutputFile : target filename when collecting missing translations.
• IgnoreJsonErrors : ignore JSON errors (recommended in production).
• LocalizerDiagnosticMode : replace localized text with X to spot missing localizations.
• AssemblyHelper : select assembly for embedded resources.

Embedded vs Files

• Embedded: use WithCulture="false" to avoid satellite assemblies and keep resources discoverable.

  <ItemGroup>
    <EmbeddedResource Include="Resources\localization.json" WithCulture="false" />
    <EmbeddedResource Include="i18n\*.json" WithCulture="false" />
  </ItemGroup>

• Files (UseEmbeddedResources = false): JSON files must be copied to the output folder.

  <ItemGroup>
    <Content Update="i18n\**\*.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </Content>
    <Content Update="common_i18n\**\*.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </Content>
  </ItemGroup>

Pluralization

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 :

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

We 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

Platform	Version
NetCore	8.0.0+
Blazor Server	8.0.0+
Blazor Wasm	8.0.0+
Blazor MAUI	8.0.0+

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.

Parent fallback: for fr-FR, both fr-FR and fr files are considered (when present) before the default fallback.

Performances (latest)

BenchmarkDotNet v0.15.8, Linux CachyOS
AMD Ryzen 9 7950X3D 2.99GHz, 1 CPU, 16 logical and 16 physical cores
.NET SDK 10.0.100
  [Host]     : .NET 10.0.0 (10.0.0, 42.42.42.42424), X64 RyuJIT x86-64-v4
  DefaultJob : .NET 10.0.0 (10.0.0, 42.42.42.42424), X64 RyuJIT x86-64-v4

Method	Mean	Allocated	Δ vs previous (latency)
Localizer	21.425 ns	-	-32.7%
JsonLocalizer	7.672 ns	-	-34.4%
JsonLocalizerWithCreation	115,225.380 ns	201,281 B	-18.1% (alloc -1.0%)
I18nJsonLocalizerWithCreation	87,230.438 ns	149,281 B	-0.7% (alloc -10.1%)
JsonLocalizerWithCreationAndExternalMemoryCache	3,308.470 ns	5,576 B	-25.0% (alloc -21.9%)
JsonLocalizerDefaultCultureValue	53.005 ns	216 B	-31.0%
MicrosoftLocalizerDefaultCultureValue	67.402 ns	216 B	-37.7%

Key levers:

• Streaming JSON (MemoryPool/ArrayPool), zero-copy on hot paths.
• Pooling of LocalizatedFormat.
• Bounded LRU cache + lock-free (ReaderWriterLockSlim) for serialized distributed cache.
• Optimized i18n key concatenation.
• Bounded/TTL collection of missing translations to avoid memory leaks.

Contributors

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

License

MIT Licence