Translating Plugin Text

The ITranslatablePlugin allows you to define language resource strings for use within a plugin that can be translated through the Verint Community platform. 

[toc]

Why Should I Translate My Plugins?

When creating a plugin for reuse or creating a plugin to be used in a community that may grow beyond the scope of a single language or culture, it is important to plan for globalization. One step in that process is ensuring that the text generated for end-user consumption can be easily translated. Verint Community provides support for translating text used by plugins via interaction with the ITranslatablePlugin plugin type.

Creating a Translatable Plugin

To add support for translating the text rendered by your plugin, implement the ITranslatablePlugin interface (which requires a reference to Telligent.Evolution.Components.dll). The ITranslatablePlugin interface extends IPlugin to add support for translation.

First, we'll define one or more primary set of translations using the DefaultTranslations property of the ITranslatablePlugin interface:

public Translation[] DefaultTranslations
{
    get 
    { 
        var translation = new Translation("en-us");

        translation.Set("my_translation_hello", "Hello");
        translation.Set("my_translation_world", "World");
        
        return new Translation[] { translation };
    }
}

This sample defines a default translation for US English (en-us) with two translated resources: "hello" named my_translation_hello and "world" named my_translation_world. The resource name is used to retrieve the translated string from the platform.

By defining the default set of translations, Verint Community can expose these options via the plugin resource export and import process to enable the default strings to be translated into other languages enabled by the community. to retrieve these translations, the plugin should request the translation from the platform using the translation controller provided to the plugin via the SetController() method of ITranslatablePlugin:

private ITranslatablePluginController _translationController;

public void SetController(ITranslatablePluginController controller)
{
    _translationController = controller;
}

Generally, the controller is stored in an instance variable of the plugin for later use. Once received during plugin initialization, the translation controller can be used to retrieve translated resource strings.

Here's the complete source of our sample translatable plugin:

using Telligent.Evolution.Extensibility.Version1;

namespace Samples
{
    public class SampleTranslationPlugin : IPlugin, ITranslatablePlugin
    {
        #region IPlugin

        public string Name
        {
            get { return "Sample Translatable Plugin"; }
        }

        public string Description
        {
            get { return "This plugin will demonstrate how the ITranslatablePlugin works"; }
        }

        public void Initialize()
        {
        }

        #endregion

        #region ITranslatablePlugin

        public Translation[] DefaultTranslations
        {
            get
            {
                var translation = new Translation("en-us");

                translation.Set("my_translation_hello", "Hello");
                translation.Set("my_translation_world", "World");

                return new [] { translation };
            }
        }

        private ITranslatablePluginController _translationController;

        public void SetController(ITranslatablePluginController controller)
        {
            _translationController = controller;
        }

        #endregion
    }
}

Once this sample is deployed to Verint Community, the plugin will show in Administration > Translations > Translatables to enable on-site translation:

and its language resources will be included in the import/export of language resources for all plugins at Administration > Translations > Plugin Translations to enable bulk/off-site translation.

Using Translated Resource Strings

Once you've implemented ITranslatablePlugin, you should use the translation controller to retrieve translated text using the resource names you defined in your default translation. Using the sample above, we could interact with the _translationController instance variable of the plugin to retrieve the translation for "hello":

string hello = _translationController.GetLanguageResourceValue("my_translation_hello");

The GetLanguageResourceValue() method of the translation controller will return the best matching translation of the requested language resource for the current accessing user (if the explicit language is not provided) or for the explicit language provided.

Translated language resource strings are useful when implementing other plugin types that interact with users via the UI or background processes.