Add translateString method

This allows to translate a string of text programmatically, using the
string translation provided.

Author: darksmo

README.md

@@ -70,7 +70,8 @@ labelTemplate | string | `{{country}} {{(language)}}` | a template string to int
 
 Method | Argument | Description
 ------ | -------- | -----------
-translate | string (languageCode) | translates the text in the given language programmatically, if no language code is specified, the default (initial) translation is used.
+translateString | string (textToTranslate), string (languageCode) | translates the given textToTranslate in the given languageCode. Note, this method just translates without creating side effects, returning the translated string. |
+translate | string (languageCode) | translates the text in the DOM to the given language programmatically, if no language code is specified, the default (initial) translation is used.
 destroy | None | destroys the localization tool
 
 #### JSDoc

src/jquery.localizationTool.js

@@ -805,6 +805,42 @@
 
             return $this;
         },
+        /**
+         * Translates a given string.
+         *
+         * @param {string} textToTranslate
+         *  A string of text to be translated. Requires the string is defined
+         *  during plugin initialization.
+         * @param {string} languageCode
+         *  A known language code like 'de_DE'
+         *
+         * @returns {string}
+         *  The translated string. The method throws an error if it was not
+         *  possible to translate the string.
+         */
+        'translateString' : function (textToTranslate, languageCode) {
+            var $this = this;
+            var settings = $this.data('settings');
+            var stringsObj = settings.strings;
+
+            if (!settings.languages.hasOwnProperty(languageCode)) {
+                $.error('The language code ' + languageCode + ' is not known');
+                return;
+            }
+
+            if (!stringsObj.hasOwnProperty(textToTranslate)) {
+                $.error('The string \'' + textToTranslate + '\' was not translated in any language.');
+                return;
+            }
+
+            var oTranslations = stringsObj[textToTranslate] || {};
+            if (!oTranslations.hasOwnProperty(languageCode)) {
+                $.error('A translation for the string \'' + textToTranslate + '\' was not defined for language ' + languageCode + ". Defined languages are: " + Object.keys(oTranslations).join(", "));
+                return;
+            }
+
+            return oTranslations[languageCode];
+        },
         /**
          * Destroys the dropdown widget.
          *

test/localizationTool_test.js

@@ -1024,4 +1024,81 @@
     }, 'out of left bound of array');
   });
 
+
+  //////////////////////////////////////////////////////////////////////////////
+  Q.module('translateString', { beforeEach: function () {
+    addDropdownWidgetFunc();
+  }});
+  Q.test('translates a string with provided translation', function (assert) {
+    var $dropdown = $('#dropdown').localizationTool({
+        strings: {
+            'this is some text' : {
+               'it_IT' : 'this is some translation 1',
+               'jp_JP' : 'this is some translation 2',
+               'fr_FR' : 'this is some translation 3'
+            }
+        }
+    });
+
+    assert.equal($dropdown.localizationTool('translateString',
+        'this is some text',
+        'it_IT'
+    ), 'this is some translation 1', 'got the expected string');
+
+  });
+
+  Q.test('throws an error when translation is made on an unknown language', function (assert) {
+    var $dropdown = $('#dropdown').localizationTool({
+        strings: {
+            'this is some text' : {
+               'it_IT' : 'this is some translation 1',
+               'jp_JP' : 'this is some translation 2',
+               'fr_FR' : 'this is some translation 3'
+            }
+        }
+    });
+    assert.throws(function () {
+        $dropdown.localizationTool('translateString',
+            'this is some text',
+            'fooLanguage'  // this language is not knwon
+        );
+    }, /The language code fooLanguage is not known/);
+  });
+
+  Q.test('throws an error when translation is not defined for the given language', function (assert) {
+    var $dropdown = $('#dropdown').localizationTool({
+        strings: {
+            'this is some text' : {
+               'it_IT' : 'this is some translation 1',
+               'jp_JP' : 'this is some translation 2',
+               'fr_FR' : 'this is some translation 3'
+            }
+        }
+    });
+    assert.throws(function () {
+        $dropdown.localizationTool('translateString',
+            'this is some text',
+            'de_DE'
+        );
+    }, /A translation for the string 'this is some text' was not defined for language de_DE. Defined languages are: it_IT, jp_JP, fr_FR$/);
+  });
+
+  Q.test('throws an error when string is not translated in any language', function (assert) {
+    var $dropdown = $('#dropdown').localizationTool({
+        strings: {
+            'this is some text' : {
+               'it_IT' : 'this is some translation 1',
+               'jp_JP' : 'this is some translation 2',
+               'fr_FR' : 'this is some translation 3'
+            }
+        }
+    });
+    assert.throws(function () {
+        $dropdown.localizationTool('translateString',
+            'this is some other text',
+            'de_DE'  // this language is not knwon
+        );
+    }, /The string 'this is some other text' was not translated in any language./);
+  });
+
 }(jQuery));