Adding a Language vs. 1.1.0 Full+Lite

Language files are an easy way to allow translation of components or JavaScript output without having to re-write the same code for each language.

Difference Between Full & Lite Versions

Since the Lite version does not include the ng.XHR object, the language files cannot be added using an Ajax request. Therefore, the language variables are placed in an object located on the top of the ng_lite.js file. The object keys and values are the same as the object used in the language files; however, the structure is a bit different.

You still need to set the default language in the Configuration as you would do with the full version. By default, the English language object is already set and ready to use by the ng.Language.set_language method. If you would like to add a new language, you would need to create a new object under the ng_lang. For example, adding Chinese would be done as the following
ng_lang.zh = {
    general: { /* see the code below for the variables */ }
}

Creating the Files

When adding a new language, you would need to locate the language directory inside the assets directory.
assets/language/
Inside the language folder, there is a folder for each language used by the NoGray framework. For example, the English files are located under
assets/language/en/
The easiest way to create a new set of language files is to copy the English folder and rename it to the language initials. For example, to add Chinese, you can copy the en folder and rename it to zh
assets/language/zh/
To add a new language, you need a minimum of a general.js file inside your language folder. If the website is using components that require translation, you need to include these files as well. For example,
assets/language/zh/general.js
If using the calendar component, the calendar file need to be included
assets/language/zh/calendar.js

How to Translate the Files

Each language file includes a JavaScript object with the text used by the script plus some additional localization variables. After creating the object, you would need to call the ng.Language.set_language method to register your variables. The example below shows the general.js file in English and Chinese. Please note that all the object keys must be in lower case since not all languages use upper and lower case letters.

English | Chinese
var en_lang = {
    // the language direction, left to right
    // (use rtl for right to left)
    direction: 'ltr',

    // the numbers from 0 to 9
    numbers: ['0','1','2','3','4',
              '5','6','7','8','9'],
    numbers_ordinal: ['st', 'nd', 'rd', 'th'],
	
    // general dates variables
    date: {
        // localize date format
        date_format: 'm/d/Y',
		
        // localize time format
        time_format: 'h:i A',
	
        // days variables
        days:{
            'char':['S','M','T','W','T','F','S'],
            short:['Su','Mo','Tu','We','Th','Fr','Sa'],
            mid:['Sun','Mon','Tue','Wed','Thu','Fri','Sat'],
			
            'long':['Sunday','Monday','Tuesday',
                    'Wednesday','Thursday','Friday','Saturday']
        },
		
        // months variables
        months:{
            short:['Jan','Feb','Mar','Apr','May','Jun',
                   'Jul','Aug','Sep','Oct','Nov','Dec'],
				   
            'long':['January','February','March','April',
                    'May','June','July','August','September',
                    'October','November','December']
        },
		
        // time variables
        am_pm:{
            lowercase:['am','pm'],
            uppercase:['AM','PM']
        }	
    },

    // general text
    yes: 'Yes',
    no: 'No',
	
    'open': 'Open',
    'close': 'Close',
    clear: 'Clear'
}

ng.Language.set_language('en', en_lang);

How about Dynamic Content

If the website utilize server side content that cannot be stored in a JavaScript easily or if the content changed frequently, you can simply add the translated content to the page using the ng.Language.set_language(obj, lang) function. We recommend to load the general.js file initially using the ng.Language.load(fle, lang) function since the general.js containes basic content for numbers, dates, etc. However, you can add any strings to any language at any time as long as the function is called after the ng_all.js file is loaded.
Example:
// adding "Hello World" in English
ng.Language.set_language('en', {hello_world: 'Hello World'});

// adding "Hello World" in Chinese (Google Translation)
ng.Language.set_language('zh', {hello_world: '你好世界'});

// alert "Hello World" in Chinese
alert(ng.Language.t('hello_world', 'zh'));

Special Functions

There are a few special functions that can be added in the general.js file to help with translating special cases. At the current release there are three special functions that can be added in the general.js language files. These functions deals with numbers and dates as the following:
  • ng.Language.translate_numbers(str, lang):
    This function help in translating numbers from English to a given language in a string. By default, it replaces the English numbers into the digits from the general.js numbers array. Since numerical systems may vary for different languages, a specific language function can be added to override this behavior. In the general.js file, you would add a function into the ng.Language object as the following
    ng.Language.[**]_translate_numbers
    
    Where [**] is the language initials. For example, to add a special function to translate numbers from English to Chinese, we would add the following function in the /zh/general.js file.
    ng.Language.zh_translate_numbers = function (str, lang){
    // .. translate the digits in here
    }
    
  • ng.Language.numbers_to_english(str, lang):
    This function reverse the ng.Language.translate_numbers function and change digits from the givin language (lang) into English digits. The same can be done to override this function by creating a special case in the general.js file as the following:
    ng.Language.[**]_numbers_to_english
    
    Where [**] is the language initials. For example, to add a special function to translate numbers from Chinese to English, we would add the following function in the /zh/general.js file.
    ng.Language.zh_numbers_to_english = function (str, lang){
    // .. translate the digits in here
    }
    
  • ng.Language.date_to_english(dt_str, lang):
    This function translates a date string from a given language (lang) into English. It uses the date object in the general.js file to translate the months and days names. This function does not translate the "short" or "char" days names since they are too short and can be part of a different word. A special case function can be added in the general.js function for a specific language as the following:
    ng.Language.[**]_date_to_english
    
    
    Where [**] is the language initials. For example, to add a special function to translate dates from Chinese to English, we would add the following function in the /zh/general.js file.
    ng.Language.zh_date_to_english = function (dt_str, lang){
    // .. translate the date here
    }
    

Reserved Words

The following reserved words should not be used as the key in any translation object. If you want to use the these words in translation, you can add a different key (e.g. {direction_txt: 'Direction'}).
  • direction: this is a string for the language direction (ltr or rtl)
  • numbers: this is an array for the language numbers from 0 to 9
  • numbers_ordinal: this is an array for the numbers ordinals (st, nd, rd, th)
  • date: this is an object for the date variables