Localization of Add ins

Home > Reference Manual > Localization of Add-ins

Mono.Addins has some basic support for creating add-ins localized to different languages. It provides:

• 3 types of localizers: ''gettext'', string resources and string table, but it is possible to use custom localizers by implementing the IAddinLocalizerFactory interface.

• An API to be used by add-ins and hosts to get translated strings.

You can use the element in an add-in manifest to enable localization support in an add-in. For example:

<Addin ...>
    <Localizer type="Gettext" catalog="xml-addin" />
</Addin>

Localization with gettext

The Gettext localizer type can be used to localize an add-in with ''gettext''. The localizer can be declared like this:

<Addin ...>
    <Localizer type="Gettext" catalog="xml-addin" location="locale"/>
</Addin>

The attributes you can set are:

• catalog: Name of the catalog which contains the strings.
• location: Relative path to the location of the catalog. This path must be relative to the add-in location.

The path specified in location (or the default ''locale'' path when not specified) must have the following structure:

<language-id>/LC_MESSAGES/<catalog>.mo

For example, the localizer defined by the previous example would read spanish strings from this file relative to the add-in location:

locale/es/LC_MESSAGES/xml-addin.mo

Localization with String Resources

The StringResource localizer type can be used to localize an add-in using string resources defined in satellite assemblies. The localizer can be declared like this:

<Addin ...>
    <Localizer type="StringResource" />
</Addin>

No additional attributes are required. Satellite resource assemblies just need to follow the standard .NET name and location conventions (see http://msdn2.microsoft.com/en-us/library/21a15yht.aspx Creating Satellite Assemblies in MSDN).

Localization with String Table

The StringTable localizer type can be used for add-ins with very basic localization needs. Translated strings are specified in a table embedded in the add-in manifest. For example:

<Addin ...>
    <Localizer type="StringTable">
        <Locale id="es">
            <Msg id="XML file" str="Fichero XML" />
            <Msg id="Header" str="Cabecera" />
            ...
        </Locale>
        <Locale id="ca-ES">
            <Msg id="XML file" str="Arxiu XML" />
            <Msg id="Header" str="Capçalera" />
            ...
        </Locale>
        ...
    </Localizer>
</Addin>

Where:

• /Addin/Localizer/Locale: Defines a string table for a language.
• /Addin/Localizer/Locale/@id: Identifier of the language. Can include the country id.
• /Addin/Localizer/Msg: Defines a new message translation.
• /Addin/Localizer/Msg/@id: Identifier of the message.
• /Addin/Localizer/Msg/@str: Translation of the message.

Custom Localizers

Custom localizers can be provided by implementing the IAddinLocalizerFactory interface. For example:

namespace LocalizerExample
{
    public class MyLocalizerFactory: IAddinLocalizerFactory
    {
        public IAddinLocalizer CreateLocalizer (RuntimeAddin addin, NodeElement element)
        {
            // You can use the 'element' object to get attributes specified in the <Localizer> element.
            return new MyLocalizer ();
        }
    }

    public class MyLocalizer: IAddinLocalizer
    {
        public string GetString (string msgid)
        {
            if (msgid == "Hello World")
                return "Hola Mundo";
            else
                return msgid;
        }
    }
}

If the localizer supports plural forms (like ''gettext'' does), you can implement IPluralAddinLocalizer in addition to IAddinLocalizer.

This custom localizer can be declared in an add-in like this:

<Addin ...>
    <Localizer type="LocalizerExample.MyLocalizerFactory" />
</Addin>

Getting Localized Strings

Localized strings defined in an add-in can be retrieved using a AddinLocalizer object. You can get an AddinLocalizer in two different ways:

• From any assembly of the add-in, by calling AddinManager.CurrentLocalizer. This property returns the localizer corresponding to the current executing add-in.
• From any ExtensionNode subclass by calling RuntimeAddin.Localizer.

The AddinLocalizer class provides several methods for getting strings. For example, from a class implemented in the add-in, a string might be retrieved like this:

class SomeAddinWindow: Gtk.Window
{
    Gtk.Label labelModigied = new Gtk.Label ();

    public SomeAddinWindow ()
    {
        Title = AddinManager.CurrentLocalizer.GetString ("XML file");
        labelModified = AddinManager.CurrentLocalizer.GetPluralString ("Modified {0} day ago", "Modified {0} days ago", numDays, numDays);
    }
}

See the Localizable extension nodes section to know more about creating localizable extension node types.