rskibbe.I18n.Json – A JSON file based translation sub-package

What is rskibbe.I18n.Json?

This is a sub-package of rskibbe.I18n to provide you with basic implementations for JSON file based translations. Now, go ahead and translate Windows Forms, WPF and Console applications – but easy. Multi-Language / internationalized apps – let’s go!

In the next few paragraphs, I’m going to show you, how to get started. As you’ve probably already seen, this package is a sub-package of rskibbe.I18n, so don’t forget to install that base package as well. As the name already suggests, rskibbe.I18n.Json focusses on file based translations using the JSON format.

💡 In a hurry?: No problem, just navigate to the points of interest by using the table of contents from above.

How to get started?

You can use the NuGet Package Manager from Visual Studio to install this package. If you are in Visual Studio, just click the „Extra“ menu button on top and navigate to the corresponding item. You could also do a right click on your project (inside the project explorer on the right side) and click „manage NuGet packages“ next. Now, just search for „rskibbe.I18n“ and you should be able to see every matching package – and there will be some 😉.

Or you could just use the following NuGet console commands:

// install the base package first
Install-Package rskibbe.I18n

// then execute this as well, to install the sub-package
Install-Package rskibbe.I18n.Json

Namespaces

After you have successfully installed both packages, go ahead and import the namespaces to get started. This will make the builder available, so you can get going fast. I won’t go to deep on the details of the base package, please refer to its own documentation for that.

using rskibbe.I18n.Models;
using rskibbe.I18n.Json;

Imports rskibbe.I18n.Models
Imports rskibbe.I18n.Json

Now you are ready to build your custom Translator fitting your individual Windows Forms, WPF, or Console App.

Setup

Creating the folder structure

Inside your output directory (where the finished exe resides, like bin/debug..), create this folder structure: The „i18n“ base folder at first, then the additional subfolder „json“. Inside of that „json“ folder, create the listed files:

• bin
  • debug
    • i18n
      • json
        • languages.json
        • en-US_English.json
        • de-DE_Deutsch.json

languages.json

This file represents/contains all available languages for your application – remember, in JSON format. Matching example contents to the example from above could look like this:

[{"iso": "de-DE", "name": "Deutsch"},{"iso": "en-US", "name": "English"}]

I specified the german and english language over here. Each one with a name and an iso „property“.

Translation files

Next, we will take a look at the translation files like „en-US_English.json“ from above. As you can see, you need to first mention the iso code (should correspond to your language file of course!). Then you just append an underscore with the specific language name.

The corresponding files from above would look like this:

Simple

en-US_English.json

{"key1": "Actions", "greeting": "Hello!"}

de-DE_Deutsch.json

{"key1": "Aktionen", "greeting": "Hallo!"}

The corresponding translation key would be „key1“, which would result in „Actions“ or „Aktionen“ depending on the language.

Namespaces / nested

en-US_English.json

{"frmMain": {"tsmiActions": "Actions"}}

de-DE_Deutsch.json

{"frmMain": {"tsmiActions": "Aktionen"}}

The corresponding translation key would be „frmMain.tsmiActions“, which is a „namespaced“ / nested one.

Code

Don’t forget to take a look at the base package setup, if you need more information. Here’s just an easy setup using the installed JSON implementations of ILanguagesLoader & ITranslationTablesLoader. Setting up the translator should be done as early as possible.

In the next step, we are telling the TranslatorBuilder to actually use the provided loaders from the package. It will then know „how do I load the languages“ and „how do I load the corresponding translations“. Don’t forget the imports mentioned above!

// don't forget the imports somewhere above..
using rskibbe.I18n.Models;
using rskibbe.I18n.Json;

// create and save the instance for later, DI, etc.
var translator = Translator.Builder
     .WithLanguagesLoader<JsonLanguagesLoader>()
     .WithTranslationTableLoader<JsonTranslationTableLoader>()
     .Build()
     .StoreInstance();

' don't forget the imports somewhere above..
Imports rskibbe.I18n.Models
Imports rskibbe.I18n.Json

' create and save the instance for later, DI, etc.
Dim translator = Translator.Builder _
     .WithLanguagesLoader(Of JsonLanguagesLoader)() _
     .WithTranslationTableLoader(Of JsonTranslationTableLoader)() _
     .Build() _
     .StoreInstance()

Full Code example

This is how a full code example could look like (don’t forget to install all needed packages and import the namespaces):

using rskibbe.I18n.Json;
using rskibbe.I18n.Models;

namespace <YourProjectName>;

public partial class Form1 : Form
{
    public Form1()
    {
        var translator = Translator.Builder
            .WithLanguagesLoader<JsonLanguagesLoader>()
            .WithTranslationTableLoader<JsonTranslationTableLoader>()
            .Build()
            .StoreInstance();
        InitializeComponent();
        Load += Form1_Load;
    }

    private async void Form1_Load(object? sender, EventArgs e)
    {
        await Translator.Instance.LoadLanguagesAsync();
        // after the languages have been loaded, the translator
        // set the language automatically, if WithLanguage("en-US")
        // has been used during initialization
        // if not, you could just trigger the initial language
        // change/set now
        // await Translator.Instance.ChangeLanguageAsync("en-US");

        // you could now get a specific translation by
        // (keep in mind, that on using WithLanguage, you
        // would actually need to like listen to the initial
        // LanguageChanged event, to get the translation)
        ITranslation translation = Translator.Instance.Translate("key1");
        // translation.Value -> Actions in en-US, Aktionen in de-DE
    }
}