curtisy1 / intl.net

A ResX Globalization alternative using JSON instead of bulky XML

Intl.Net

A ResX Globalization alternative using JSON instead of bulky XML.

Generates strongly-typed resource classes for looking up localized strings.

Usage

Install the Intl.Net.ResourceGenerator and Intl.Net.ResourceManager packages in your resource project:

Make sure to copy your JSON resource files to your output directory and mark them as EmbeddedResource

<EmbeddedResource Include="Localization.json">
  <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
</EmbeddedResource>

For a list of configurable options, as well as supported i18n providers that fetch your translations from a remote API, please see the wiki pages.

Performance

Currently, Intl.Net is just as fast as the Resx ResourceManager shipped with dotnet itself. In cases where trying to get a non-existing key, it is even significantly faster.

For details and the benchmarks run, check the benchmarks folder.

Related libraries

If this library looks amazing, please do check out these similar projects and give them a star!

TypealizR - A source generator doing the same thing for .resx files. It's pretty much a modern Globalization alternative

intl.net's Issues

Add benchmark sample

It would be nice to have some kind of benchmark to compare if this has any performance difference to the built-in ResourceManager.

Ideally, we'd have one with a few and one with a lot of keys and cultures

Introduce a concept of JSON namespaces

It would be great to have some kind of namespacing concept to distinguish this library from the built-in resx generator.

• Instead of a simple key-value mapping, introduce a key-object mapping
• Each object is a class on its own, residing in the global namespace
• Nesting is allowed up to a certain depth of x

The following json should generate something like this, for reference:

{
	"Key": "Value",
	"AnotherKey": {
		"NestedKey": "NestedValue"
	}
}

Option 1:

namespace ABC {
	public class CBA { // default namespace. Every key-value pair goes here
		public string Key => "Value";
	}

	public class AnotherKey {
		public string NestedKey => "NestedValue";
	}
}

Option 2:

namespace ABC {
	public class CBA {
		public string Key => "Value";

	    public class AnotherKey {
		    public string NestedKey => "NestedValue";
	    }
	}
}

Improve flaky tests

The tests are somewhat flaky and work on string output. Having a few json files with good, bad and super evil input and generating actual files out of these would be a better approach

Multi file handling

Again, something to improve and implement the resx generator doesn't have

Provide a system for reading from multiple file sources and bundling them into a single namespace/file (if desired)

• Think of a reasonable grouping scheme
  • Group files in csproj or
  • Group files based on name, e.g Localization.ABC.json and Localization.DEF.json would belong together
  • Do not group at all. Every file that doesn't end in a locale is a class
• This needs to play nicely with #11
• Provide an option for generating everything in a single file or multiple files

Rename the project

To be honest, the name is a bit weird. Let's rename it to attract more attention and sound cool

Feature parity with dotnet resx generator

Dotnet has their own internal source generator, transforming resx files into strongly typed objects.

From a quick look, it has a few cool options. We should aim for feature parity

Find a way to copy the resulting file to the project directory

The generated file currently gets saved in obj/... however for code-completion it needs to be somewhere in the project directory. There seems to be a Copy Task that's worth investigating

Handle special characters better

Currently, only a few characters are escaped and sanitized. This is because they appeared in the sample I was testing with at work. However, there's probably a bunch of other evil characters out there the generator should handle (how about ?, !, comma, ', ", <,>) to name just a few

• Check how the official resx ResourceGenerator does escape these. Get at least feature parity (no code stealing)
• Every breaking character gets replaced with a _. The ResourceManager should be able to find both variants (e.g. for JS parsing)
• How do we deal with exotic characters or emojis? Are these even supported in resx? I know Csharp does not support them, so experiment and provide as much support as possible

Create Wiki entries for available options and plugins

There are quite a few options available for this plugin. Set up a github.io or wiki page that explains everything in a bit more detail

Allow integration with i18n providers

We should be able to fetch JSON translations from i18n providers as long as they support exporting. Ideally, this should be a plugin system where each provider is a standalone Nuget package that can be easily integrated.
The minimum supported features would be something along the lines of

• Fetch translations from API
• Do any custom transformations necessary (such as unzipping etc.)
• Add them to the build process as an additional source

For reference, here is a non-exhaustive list of providers

• Weblate
• Crowdin
• Localazy
• Locize
• POEditor
• Tolgee (@curtisy1)

They're all up for grabs, since maintaining all of these is too tedious. So when you need them, please contribute!