myLanguages - Cross-Platform Localization Engine

myLanguages is a cross-platform API that allows you to convert your applications into multi-language applications and share them across the world!

It's cross-platform so you can use it in Xamarin, .NET Core, MVC, Mono and .NET Framework projects

Features

• Easy to use
• Fast implementation on any platform
• Language changing at runtime
• No .resx files
• Posibility to automatically add new languages
• Ready to use WPF implementation

Installation

You can install the latest version of myLanguages via Nuget Package Manager

PM> Install-Package myLanguages.Core

And the WPF implementation

PM> Install-Package myLanguages.Wpf

Usage

You can only have one instance of the Localization Engine in your entire application. Before start using it, you need to create that instance.

The Engine

Instantiation

To instantiate it, you will use the LocalizationEngine class and the MakeNew(ILanguageDecoder) method, which take one parameter:

decoder ILanguageDecoder

The decoder used to load languages

There are already two built-in language decoders you can use:

• EmbbededLanguageDecoder Will search for files with the .lang extension in the embedded files of your application.
• EmbbededLanguageDecoder(string) Will search for files with the .lang extension in the directory that you specified in the parameter

NOTE: You can create your own decoder by implementing the ILanguageDecoder interface in your class.

This method will return you the unique instance of the Localization Engine. Or, you can use LocalizationEngine.Instance to get it from anywhere.

var instance = LocalizationEngine.MakeNew(new PhysicalFileDecoder("InstallationPath\\Langs"));

Languages

Defining a language

A language is simply a file which its name is the language name and the extension MUST be .lang. Entries are defined one per line, the first value is the key, the second is the text between quotes that the key represents.

File name: en-US.lang

This will create a language with a subculture (US), but, it can be only the native culture (en)

File content:

Texts.Welcome="Welcome to my application!"
Texts.Title1="Great Application"
Texts.Title2="Made by Tomas Wegenast"
Pages.AboutUs.MadeBy="This library was made by:"
Pages.AboutUs.SupportUs="You can help us by donating in our Patreon page:"

Loading languages

To start searching and loading all the found languages, you will use the DetectLanguages(string) method, which takes an optional parameter:

defaultLanguage string

The default language to use in the application. This must be a valid loaded language. If the parameter is not provided, the API will get the system language and try to set that language.

int loadedLangs = LocalizationEngine.Instance.DetectLanguages();

Adding new languages automatically

You can use the AddOnlineLanguage(Language, CultureInfo) method to add languages based on the input language which take two parameters:

sourceLanguage Language

The language to be translated

toLanguage CultureInfo

The language to translate to

This method has two overloads:

• AddOnlineLanguage(Language, CultureInfo, IOnlineTranslator) Which takes as parameters the language to be translated, the language to translate to, and the service to use.
• AddOnlineLanguages(Language, string[]) Which takes as parameters the language to be translated, and an array of strings containing the languages to translate

NOTE: This method reads the input language file, get all the entries and translate them using an Online service

Translator services can be created by implementing the interface IOnlineTranslator

There is already one built-in online translator service:

• GoogleTranslator Uses the Google Translation services to translate your entries

Changing the Language

You can change the current language of your application at runtime using the ChangeLanguage(string) method, which takes one parameter:

languageCode string

The new language to set the application

LocalizationEngine.Instance.ChangeLanguage("en-US");

This method will try to change your application's language to the specified in the parameter. If you specify a Subculture (en-US), first of all, this language will be searched. If it was not found, the Engine will take the Culture (en-US) and search for a language that contains it. If everything fails, an exception will be thrown.

Retrieving an entry

To get an entry, you only need the key of the entry and use the indexer property Localizator

string translatedValue = LocalizationEngine.Localizator["Titles.Principal"];

WPF implementation

If you are working in a WPF project, you can install the WPF implementation package and work easily.

You don't need any xmlns reference. To locate an entry you will use the Loc(Key) markup extension.

<Button Content="{Loc Key=Titles.Welcome}" />

<TextBlock Text="{Loc Texts.TextBlock}" />

<TextBox Text="{Loc KeySource={Binding myKey}" />

If you want to show a default text if the key is not found or something fails, you can use the FallbackValue property

<TextBlock Text="{Loc NotFound.Key, FallbackValue=My default value}" />

Useful Methods & Properties

To get all the installed languages:

IEnumerable<Language> installedLangs = LocalizationEngine.Instance.GetInstalledLanguages();

Gets the current language of the application:

Language currentLang = LocalizationEngine.Instance.CurrentLanguage;

To get a language:

Language esLang = LocalizationEngine.Instance.GetLanguage("es");

Summary

// Console app's entry point
static void Main(string[] args)
{
    // Setup the Localization Engine
    LocalizationEngine.MakeNew("AppData\\MyApp\\langs");

    // Detect languages and set by default French
    LocalizationEngine.Instance.DetectLanguages("fr");

    // Print installed langs
    Console.WriteLine("Installed languages:");
            foreach (var lang in LocalizationEngine.Instance.GetInstalledLanguages())
                Console.WriteLine($"\t- {lang.ToString()}");

    // Print welcome message
    Console.WriteLine(LocalizationEngine.Localizator["Texts.Welcome"]);

    Console.ReadLine();
}

License

Licensed under GNU General Public License v3.0

For more information read LICENSE.txt

Donate

Buy me a Fernet ;)