Tutorials-Loading

Flexible Localization Tutorials: Loading the first Localization

This tutorial assumes that you have already created a localization declaration and at least one localization. Also, C# is going to be the language used, access from other .NET languages is done in an analogous way. Note that the basic Windows Forms example that this tutorial is based upon is also available written in Visual Basic.NET, though.

Telling Flexible Localization where to look for Localizations

First of all, we need to let Flexible Localization know where localizations may be looked for. The component that performs this duty is called a localization storage, as it is usually the application's view of the file system, database or network connection that provides access to the localization data.

As our localizations are stored locally in Xml files, an instance of the LocalizationXmlFileStorage class will be used:

var locStorage = new FlexibleLocalization.IO.Xml.LocalizationXmlFileStorage(Path.Combine(Application.StartupPath, "localization"));

The argument passed to the localization storage constructor indicates that localization files should be searched for in the localization subdirectory of the application directory.

The default settings of the LocalizationXmlFileStorage class require localization filenames to match the pattern <module>.<language>.xml. As this example project only has a single module, the module part is not required in our case and we modify the filename pattern to suit our needs:

locStorage.FileNamePattern = FlexibleLocalization.IO.LocalizationFileStorage.LanguagePattern + ".xml";

Our permanent link to Flexible Localization

After preparing the localization storage, we can obtain a so-called localization manager: An object that will allow us to load localization declarations and localizations at any time.

It is a wise idea to store a reference to the localization manager at a place where it is accessible during the entire lifetime of the application. In the current example application, a private member of the main form is used:

private readonly FlexibleLocalization.LocalizationManager locManager;

This member can then be initialized right after the localization storage has been set up:

locManager = new FlexibleLocalization.LocalizationManager(locStorage);

Loading the Declaration

Now that there is a localization manager, we can load the declaration of our module:

locManager.LoadModuleFromXmlFile("default", Path.Combine(Application.StartupPath, "BasicSWFSampleLocalization.xml"));

If you named your declaration file differently, make sure to change the name here. This will tell Flexible Localization to load the specified declaration file and consider that the module default.

Using the Localization Manager

Everything is set in place now. Here are several things you might want to do:

Display a List of all available Localizations

Use the following command:

locManager.Storage.GetAvailableLocalizations("default")

It will return an IEnumerable<FlexibleLocalization.LocalizationInfo>; an enumeration that contains an information object about every detected localization for the module named default.

Load a Localization

locManager.LoadLocalization(new string[] { "en-US" });

This command will load the English (US) localization seen in the first part of the tutorial, if it was saved in the proper place with the correct name. Note that you can specify several localizations as fallbacks. Feel free to let your users choose one or more localizations themselves and don't forget that there's a ready-made control for localization selection included in the library.

Apply a loaded Localization

This is probably what you have been wondering about: Just how does the localized data finally get into the user interface?

First of all, LocalizationManager has the LocalizationUpdated event where you can register methods that fetch the localized data once a new localization has been loaded.

Once that is done, the most straightforward way is to fetch the strings from the localization storage one by one and assign them to the desired UI elements:

var loc = locManager.GetModule("default").Localization;

Text = loc["title"];
lDesc.Text = loc["desc"];
lAge.Text = loc["age"];

lOutput.Text = loc.GetString("ageOutput", tbAge.Value.ToString());

Note how the localization root of the desired module is obtained before the localized strings are retrieved. Any string decorations such as the colon for a label string are automatically applied. Also note the last line where a parametrized string is retrieved.

Now, there are more convenient methods of using the localized data:

• You can have the Wrapper Generator tool generate typesafe wrapper classes (currently, only C# is supported) for all of your localization sections, based on the declaration file. Like this, the compiler will enforce that you only retrieve existing localized strings and provide parameter values of the correct types (see the WrapperSample).
• You can use classes from the FlexibleLocalization.Bindings namespace that help you automatically assign static strings if you add objectRef subelements to the strings in the declaration (see the AutomatedLocalizerSample project).