rskibbe.I18n 1.0.5

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 most important namespace - making the builder available:

C#

using rskibbe.I18n.Models;

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. For this, it will prioritize finding a suitable ILanguagesLoader & ITranslationTablesLoader in the following order (Assemblies):

• Executing Assembly

if you for example defined your own Loaders and to lazily use them - like InMemory ones

• rskibbe.I18n.Json

Keep in mind that this is an additional package with prepared implementations you could install

• rskibbe.I18n.Ini

see the Json one..

• ⚠️ rskibbe.I18n.Web

Not available yet, for like (REST) API or general web based loading calls

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

    // or just chain the StoreInstace method
    // then "var instance = " is optional for sure
    var translator = Translator.Builder
        .Build()
        .StoreInstance();

Setting up the translator should be done as early as possible, like in some sort of bootstrapping process, or before the first Form "InitializeComponent" 'n' stuff.

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:

• rskibbe.I18n.Json
• rskibbe.I18n.Ini
• more like Web/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 - or use autodetection:

   // 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()
        .StoreInstance();

With custom loaders

The above can also be done 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()
        .StoreInstance();

InMemoryLanguagesLoader implementation:

public class InMemoryLanguagesLoader : ILanguagesLoader
{

    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 InMemoryTranslationTableLoader()
    {
    }

    public Task<List<ITranslationTable>> LoadTranslationTablesAsync(params string[] isoCodes)
    {
        var german = new Language("Deutsch", "de-DE");
        var english = new Language("English", "en-US");

        var germanTranslationTable = new TranslationTable(german)
            .AddTranslation("namespaceOne.key1", "Schlüssel 1")
            .AddTranslation("namespaceTwo.key2", "Schlüssel 2")
            .AddTranslation("btnEnglish", "Englisch")
            .AddTranslation("btnGerman", "Deutsch");

        var englishTranslationTable = new TranslationTable(english)
            .AddTranslation("namespaceOne.key1", "Key 1")
            .AddTranslation("namespaceTwo.key2", "Key 2")
            .AddTranslation("btnEnglish", "English")
            .AddTranslation("btnGerman", "German");

        var translationTables = new List<ITranslationTable>()
        {
            germanTranslationTable,
            englishTranslationTable
        };
        var requestedTranslationTables = translationTables
            .Where(x => isoCodes.Contains(x.Language.Iso))
            .ToList();
        return Task.FromResult(requestedTranslationTables);
    }
}

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();
    // the available languages can be accessed
    // Translator.Instance.Languages
    // prefill UI, etc..
}

The package also provides a basic DefaultLanguageItemViewModel or a LanguageItemViewModel as base to work on. This can help filling ComboBoxes, etc.

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

Properties

LanguagesLoader

Provides a strategy for the translator on how to load the available language.

TranslationTableLoader

Provides a strategy for the translator on how to load the available/needed translations.

Language

Reflects the currently used language or null if no language has been loaded/set.

Languages

Lists the available/loaded languages.

Methods

StoreInstance

Stores itself in the static property to avoid using another line, etc. The static instance will help with further sub-packages.

Translate

Will try to get the corresponding translation of the key, returns null if not found.

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 implementing object). This will tigger the loading of the new Translations/updating existing ones.

Will be ignored/skipped if the same language is already set

Events

LanguageChanged

Obviously occurs after the languaged has been successfully changed.