rskibbe.I18n.Winforms – Translate your Windows forms apps – but easy

What is rskibbe.I18n.Winforms?

rskibbe.I18n.Winforms is a sub-package that helps you translate your Windows Forms apps easily. It extends the other rskibbe.I18n packages to provide specialized help with the Winforms technology. Keep in mind, that there is another package for WPF as well and that you can refer to the base package for more information.

💡 In a hurry?: No problem, just navigate to the points of interest by using the table of contents from above, or watch the provided setup video down below.

Video guide

How to get started?

To begin with the easy translation of Windows Forms Apps, you first need to install the desired and essential packages. You can do so, by visiting the NuGet Package Manager of your Visual Studio installation. For sure, you can use the NuGet console as well, just as you wish. Search for the term „rskibbe.I18n“ and you will get all available packages.

What we are going to do

In this quick example, we are going to create a json file based translation for our Windows Forms App. For this, we need to install the following „rskibbe.I18n“-packages:

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

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

// in the last step, get the package for the Windows Forms stack
Install-Package rskibbe.I18n.Winforms

Namespaces

After you have completed installing the needed / desired packages, you can now go ahead and import the essential namespaces. With doing so, you are able to create the translator instance of your needs and translate your forms. Please refer to the base package documentation, if you need more information corresponding to it.

// don't forget the imports
using rskibbe.I18n.Models;
using rskibbe.I18n.Winforms;

' don't forget the imports
Imports rskibbe.I18n.Models
Imports rskibbe.I18n.Winforms

Setup

To setup your custom translator, you can just use this easy and quick method:

// before like the first Form InitializeComponent
Translator.Builder
    .WithAutoFormTranslation()
    .Build()
    .StoreInstance();

' before like the first Form InitializeComponent
Translator.Builder _
    .WithAutoFormTranslation() _
    .Build() _
    .StoreInstance()

An important note

In this case I’m using the autodetection feature, that means, I don’t need to explicitly define the used format like JSON or INI. It will see, which package we’ve installed, so it will pick it right away. In this case we are using the JSON package. Now it will automatically translate and update corresponding controls like Labels, Buttons and Forms. You don’t need to configure much more from the coding side – isn’t this nice?

Remember to do this „bestly“ before any UI going on, the Bootstrapping point Program.cs/Program.vb or like the first Form Constructor could be the best place (but make sure it doesn’t get called multiple times).

Marking controls as translatable

Away from the coding side, we are now going to configure the UI to actually take those translations. For this, you need to tell the translator: „Hey, I want this translation, to go over here„. You can do so, by just specifying its tag property inside the designer!

Currently supported Controls

At this moment, the package supports auto-translation for the following types of controls:

• Buttons
• CheckBoxes
• GroupBoxes
• Labels
• LinkLabels

Full Example

Step 1 – Install packages from NuGet

The base package is always necessary rskibbe.I18n. Depending on the translation style you want to use (InMemory, file-based like Json or Ini, etc.), install the next package like rskibbe.I18n.Json. Now you can install the last helper package for Windows Forms (this one you are looking at right now..) rskibbe.I18n.Winforms.

Step 2 – Create a „Form“

Go on like your first form – usually Form1 – and put a button on top of it. Name it as you wish, but specify the Tag property as „i18n:myTranslationKey“. The translator will search for the i18n prefix and will know, that it has to translate it with the corresponding translation key (the thing after the colon).

Step 3 – Create the necessary files

Please take a look at the corresponding package like rskibbe.I18n.Json or rskibbe.I18n.Ini for file and folder / content structures. More packages for loading from web APIs and like SQL are planned.

Step 4 – Specify the code

To let the translator handle its work, go ahead and use (for example) this code:

public partial class Form1 : Form
{
    public Form1()
    {
        Translator.Builder
            .WithAutoFormTranslation()
            .Build()
            .StoreInstance();
        InitializeComponent();
    }

    private async void Form1_Load(object sender, EventArgs e)
    {
        await Translator.Instance.LoadLanguagesAsync();
        if (Translator.Instance.HasLanguages)
        {
            var language = Translator.Instance.Languages.SingleOrDefault(x => x.Iso == "en-US");
            await Translator.Instance.ChangeLanguageAsync(language);
        }
    }

    private async void btnSetGerman_Click(object sender, EventArgs e)
    {
        await Translator.Instance.ChangeLanguageAsync("de-DE");
    }

    private async void btnSetEnglish_Click(object sender, EventArgs e)
    {
        await Translator.Instance.ChangeLanguageAsync("en-US");
    }
}

Public Partial Class Form1
    Inherits Form

    Public Sub New()
        Translator.Builder _
            .WithAutoFormTranslation() _
            .Build() _
            .StoreInstance()
        InitializeComponent()
    End Sub

    Private Async Sub Form1_Load(ByVal sender As Object, ByVal e As EventArgs)
        Await Translator.Instance.LoadLanguagesAsync()

        If Translator.Instance.HasLanguages Then
            Dim language = Translator.Instance.Languages.SingleOrDefault(Function(x) x.Iso = "en-US")
            Await Translator.Instance.ChangeLanguageAsync(language)
        End If
    End Sub

    Private Async Sub btnSetGerman_Click(ByVal sender As Object, ByVal e As EventArgs)
        Await Translator.Instance.ChangeLanguageAsync("de-DE")
    End Sub

    Private Async Sub btnSetEnglish_Click(ByVal sender As Object, ByVal e As EventArgs)
        Await Translator.Instance.ChangeLanguageAsync("en-US")
    End Sub
End Class

Please take a look at the base package for more information like getting the available languages, changing the language, etc.