rskibbe.I18n 1.0.1

Description

An infrastructure package helping you translating "things". Install corresponding sub-packages to help you translate Winforms & WPF applications - easily. Multi-Language / internationalization apps - here we come!

Getting started

After installation, just go ahead and import the corresponding namespace:

C#

using rskibbe.I18n.Models;

Examples

From there, you can build your own Translator by using the TranslatorBuilder:

Setup

Simplest, with autodetection

If you just want to "make it work", you can easily create your Translator in 1-2 simple lines. This will use the internal autodetection feature to estimate, which techniques to use. It will prioritize Json-style loading methods - if you want to learn more about this, go to "Loading Methods". If it can't find the Json ones, it will default to the first ones to find.

   // create and save the instance for later, DI, etc.
   var translator = Translator.Builder
        .Build();

    // don't forget to store it in static Property
    // to make other helpers available
    Translator.Instance = translator;

Setting up the translator should be done as early as possible, like in some sort of bootstrapping process, or the first Form.

With readily available loaders

You can tell the Translator "how to load the available languages" and "how to load the translations" by providing existing implementations of ILanguagesLoader / ITranslationTableLoader.

For this, you can take a look at my other sub-packages like (coming soon!):

• rskibbe.I18n.Json
• rskibbe.I18n.Ini
• more like Rest, SQL to come..

Those will provide you with basic loader implementations. After you've installed those, just go ahead and provide the corresponding implementations:

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

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

    // don't forget to store it in static Property
    // to make other helpers available
    Translator.Instance = translator;

With custom loaders

You can tell the Translator "how to load the available languages" and "how to load the translations" by providing custom implementations of ILanguagesLoader / ITranslationTableLoader.

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

    // don't forget to store it in static Property
    // to make other helpers available
    Translator.Instance = translator;

InMemoryLanguagesLoader implementation:

public class InMemoryLanguagesLoader : ILanguagesLoader
{
	// empty constructor is necessary
    public InMemoryLanguagesLoader() { }

    public Task<List<ILanguage>> LoadLanguagesAsync()
    {
        var languages = new List<ILanguage>()
        {
            new Language("Deutsch", "de-DE"),
            new Language("English", "en-US")
        };
        return Task.FromResult(languages);
    }
}

InMemoryTranslationTableLoader implementation:

public class InMemoryTranslationTableLoader : ITranslationTableLoader
{

    public List<ITranslationTable> AllTranslationTables { get; protected set; }
    
	// empty constructor is necessary
    public InMemoryTranslationTableLoader()
    {
        var someExampleTranslationKey = "frmAnmeldung.titel";

        var german = new Language("Deutsch", "de-DE");
        var germanTranslations = new Dictionary<string, ITranslation>()
            {
                { someExampleTranslationKey , new Translation(german, someExampleTranslationKey, "Titel") }
            };

        var english = new Language("English", "en-US");
        var englishTranslations = new Dictionary<string, ITranslation>()
            {
                { someExampleTranslationKey , new Translation(english, someExampleTranslationKey, "Title") }
            };

        var translationTables = new List<ITranslationTable>()
            {
                new TranslationTable(german, germanTranslations),
                new TranslationTable(english, englishTranslations)
            };

        AllTranslationTables = translationTables;
    }

    public Task<List<ITranslationTable>> LoadTranslationTablesAsync(params string[] isoCodes)
    {
        var translationTables = AllTranslationTables.Where(x => isoCodes.Contains(x.Language.Iso)).ToList();
        return Task.FromResult(translationTables);
    }
}

Preparation

Depending on your use case, you need to like execute the loading of the available languages by a call to the Translator LoadLanguagesAsync() method. Otherwise, you won't know, what languages are available, right? Something like a Form Load EventHandler could be the right place, remember to use async/await if wanted. You can then see the available languages inside the Languages-Property.

private async void Form1_Load(object sender, EventArgs e)
{
    // the next line, or if you have a direct reference, just use your reference of the translator..
    await Translator.Instance.LoadLanguagesAsync();
    // what languages are "available"
    // Translator.Instance.Languages
    // prefill UI, etc..
}

The package also provides a basic DefaultLanguageItemViewModel or a LanguageItemViewModel as base to work on.

Usage

After all setup and preparation steps are completed, you can then start using the Translator like this:

// get the current language
// var currentLanguage = Translator.Instance.Language

// change the current language
// using an implementation of ILanguage / the iso code string
// if you try to set it to the same language twice, the call will be ignored
await Translator.Instance.ChangeLanguageAsync("de-DE");

Functions & Methods

LoadLanguagesAsync

Loads the available languages provided by the ILanguagesLoader implementation. Will trigger the loading of the ILanguagesLoader.LoadLanguagesAsync method.

ChangeLanguageAsync

Both overloads willl try to change to the new target language (iso string, ILanguage impl. object). This will tigger the loading of the new Translations or skip if the language specified has already been set.

This function does not include the NewLine String itself.

Events

LanguageChanged

Obviously occurs after the languaged has been successfully changed.