Using Localizator


Subscribing objects

To subscribe an object, just use the Subscribe method:

loc.Subscribe(someObject);
Remember that only objects with implemented ILocalizerSubscriber can be subscribed. To unsubscribe, analogously call:

loc.Unsubscribe(someObject);
There is no particular need to surround these lines with try ... catch blocks. Localizator will do nothing if you try to subscribe the same object more than once or to unsubscribe the one that isn't already subscribed. But it throws NullArgumentException if you try to smuggle null into these methods.

Loading localization and localizing all subscribed objects

To load localization from the XML file, use the Load method. It takes one string (with a path to the file) and returns nothing.

loc.Load(@"d:\Polish.xml");
Load method throws InvalidXmlFileException if:
  • the file's path is invalid and it's impossible to create a FileInfo object with it.
  • the specified file doesn't exist.
  • the file's size is more than 1Mb.
  • there are problems with deserializing file to a Localization object.
  • the obligatory Language tag isn't inside or it's empty.
  • there are no phrases.

The thrown InvalidXmlFileException object contains all information about what happened; remember to check it's Message and InnerException!

If loading the localization went without errors, the next step is localizing all subscribed objects. To do so, run:

loc.Localize();
Localize method throws NoLocalizationLoadedException if you skipped loading the localization or if it ended unsuccessfully.

For your convenience, there is LoadAndLocalize method that allows to run both of these methods in one call. It's defined like this:

public void LoadAndLocalize(String filePath)
{
        Load(filePath);
        Localize();
}
So you can close the entire operation in one simple template:

try
{
	loc.LoadAndLocalize(@"d:\Polish.xml");
}
catch(InvalidXmlFileException exception)
{
	// reaction...
}

Getting phrases

There are two ways of obtaining the phrase from the currently loaded XML file. First is more traditional and bases on the simple method call:

// getting phrase by key
loc.GetPhrase("Sample phrase");

// getting phrase by id
loc.GetPhrase(666);

GetPhrase returns string linked with the given key value or Id.
  • It's good to know that Localizator keeps all phrases sorted by key value. So getting them by it would be much more effective (binary search is used) than by id (linear search).
The second way is more sophisticated and uses the indexer mechanism:

// getting phrase by key
loc["Sample phrase"]

// getting phrase by id
loc[666];
And it's pretty much the same, because indexers are defined like this:

// PART OF THE LOCALIZATOR CLASS:

public String this[String key]
{
        get
        {
                return GetPhrase(key);
        }
}

public String this[int id]
{
        get
        {
                return GetPhrase(id);
        }
}

Customizing "phrase not found" behaviour

It's highly probable that you will try to get a phrase by calling it by ID (or key value) that doesn't exist. It's good to know that you are able to customize the action in such situations. To do it, take a look at the public property in the Localizator class titled WhatToDoIfPhraseNotFound:

public PhraseNotFoundBehaviour WhatToDoIfPhraseNotFound { get; set; }

It keeps the behaviour and all it's variants are listed in the XMLocalizator.PhraseNotFoundBehaviour enum. Depending on your choice, GetPhrase method will:
  • ThrowException - throw PhraseNotFoundException with full information about your mistake in the exception's Message property.
    • This is set as default.
    • Example message is like: There is no phrase with Id '666' in the collection!, There is no phrase with key 'Sample phrase' in the collection!.
    • Use it if you would like to handle it in the catch block or to let the application crash.
loc.WhatToDoIfPhraseNotFound = PhraseNotFoundBehaviour.ThrowException;

try
{
	label1.Text = loc["Sample phrase"];
}
catch (PhraseNotFoundException exception)
{
	// reaction...
}

  • ReturnErrorString - return text with short information about your mistake.
    • Example text is like: ERROR! Id='666', ERROR! Key='Sample phrase'.
    • Use it if you would like to see straightway in the application which phrases are taken incorrectly.
ErrorString.jpg

  • ReturnEmptyString - return empty string
    • Using it you are able to react comparing method's answer with String.Empty.
    • Regardless of whether an error occured or not, you can still assign the answer to it's place.
loc.WhatToDoIfPhraseNotFound = PhraseNotFoundBehaviour.ReturnEmptyString;

label1.Text = loc["Sample phrase"];

if (label1.Text == String.Empty)
{
	// reaction...
}

  • ReturnNull - return null value.
    • Using it you are able to react comparing method's answer with the null value.
loc.WhatToDoIfPhraseNotFound = PhraseNotFoundBehaviour.ReturnNull;

if (loc["Sample phrase"] != null)
{
	label1.Text = loc["Sample phrase"];
}
else
{
	// reaction...
}

Getting localization data

All information which are in the XML file with localization are packed into the Localizator's properties and all of them are string values. Click here to see exactly what data you can get. Names are the same.

The information are useful and can be used to determine whether loaded localization concerns to the current application or not. For example:

// check if application is correct
if (loc.Application != "XMLocalizator Demo")
{
	// reaction...
}

// check if version of the application is correct
else if (loc.ApplicationVersion != "1.0")
{
	// reaction...
}

There are plenty other places where you can make use of it, for example in About section:

label1.Text = String.Format("{0} {1} {2} {3}", loc["Translated to"], loc.Language, loc["by"], loc.Author);

Last edited Mar 21, 2011 at 2:55 PM by bartoszlenar, version 14

Comments

No comments yet.