define(
        changeToJSON
        init
            finishI18N
            translateJqueryPlugins
            translateDirectory
            doI18N
            loadLanguageBundles
        General
            process
        getValueForKey
        UnicodeExpression
        processUTF16ToText
        getEditorLanguage
        getUserLocale
define(

class i18n
description <p>Internationalisation related functions for general page content, widget content and UI elements.</p> <p>This should only hold functions which are used across multiple pages, and does not constitute functionality related to a single area/page.</p>
namespace Internationalisation


changeToJSON : function(input) {

This changes properties file into a json object


init : function(meData) {

<p>Main i18n process</p> <p>This function will be executed once the entire DOM has been loaded. The function will take the HTML that's inside the body of the page, and load the default and user specific language bundle. We then look for i18n keys inside the HTML, and replace with the values from the language bundles. We always first check whether the key is available in the user specific bundle and only if that one doesn't exist, we will take the value out of the default bundle.</p>
param {Object} meData the data from sakai.api.User.data.me


var finishI18N = function() {

Once all of the i18n strings have been replaced, we will finish the i18n step. The content of the body tag is hidden by default, in order not to show the non-translated string before they are translated. When i18n has finished, we can show the body again. We then tell the container that pre-loading of the page has finished and that widgets are now ready to be loaded. This will mostly mean that now the general page/container code will be executed. Finally, we will look for the definition of widgets inside the HTML code, which should look like this: - Single instance: <div id='widget_WIDGETNAME' class='widget_inline'></div> - Multiple instance support: <div id='widget_WIDGETNAME_UID_PLACEMENT' class='widget_inline'></div> and load them into the document


var translateJqueryPlugins = function() {

Function that will internationalize the different jquery plugins we use. For example, we want to make sure that the previous and next buttons in the pager plugin are properly using the current user's locale settings


var translateDirectory = function(directory) {

Translate all of the elements inside of the directory into the current's language


var doI18N = function() {

This will give the body's HTML string, the local bundle (if present) and the default bundle to the general i18n function. This will come back with an HTML string where all of the i18n strings will be replaced. We then change the HTML of the body tag to this new HTML string.
param {Object} localjson JSON object where the keys are the keys we expect in the HTML and the values are the translated strings
param {Object} defaultjson JSON object where the keys are the keys we expect in the HTML and the values are the translated strings in the default language


var loadLanguageBundles = function() {

This will load the default language bundle and will store it in a global variable. This default bundle will be saved in a file called bundle/default.properties. This function will load the general language bundle specific to the language chosen by the user and will store it in a global variable. This language will either be the prefered user language or the prefered server language. The language will be available in the me feed and we'll use the global sakai.api.User.data.me object to extract it from. If there is no prefered langauge, we'll use the default bundle to translate everything.


General : {

class i18nGeneral
description Internationalisation related functions for general page content and UI elements
namespace General internationalisation functions


process : function(toprocess, widget) {

General process functions that will replace all the messages in a string with their corresponding translation.
example sakai.api.i18n.General.process( '<h1>__MSG__CHANGE_LAYOUT__</h1>', {'__MSG__CHANGE_LAYOUT__' : 'verander layout'}, {'__MSG__CHANGE_LAYOUT__' : 'change layout'} );
param {String} toprocess HTML string in which we want to replace messages. Messages have the following format: __MSG__KEY__ in the default language
param {String} widget optional widget name. This will cause the widget language bundles to be checked for a translation first
return {String} A processed string where all the messages are replaced with values from the language bundles


getValueForKey: function(key, widgetname) {

Get the internationalised value for a specific key. We expose this function so you can do internationalisation within JavaScript. If the key isn't found in a translation bundle, the key will be returned unmodified
example sakai.api.i18n.getValueForKey('CHANGE_LAYOUT', ['widgetid']);
param {String} key The key that will be used to get the translation
param {String} optional widget name. This will cause the widget language bundles to be checked for a translation first
return {String} The translated value for the provided key


UnicodeExpression: new RegExp('[\\][u][A-F0-9]{4}', 'g'),

Utility regular expression that is used to find escaped unicode characters in translation string


processUTF16ToText: function(translation) {

Utility function that will take a translation string and replace escaped unicode characters with the actual unicode character
param {String} translation Translation key that we want to scan for escaped unicode
return {String} Translation key where all escaped unicode characters have been replaced by the actual unicode character


getEditorLanguage: function() {

Get the language for the editor for the current user If the editor language doesn't exist, we default to English
return {String} The language for the current user (e.g. 'nl')


getUserLocale: function() {

Function that will return the current user's locale Example: en_GB