Internationalization -- How to guide

Localization

Localization is used to format Dates and Numbers to the standards of a particular location or country.

Date Example: mm/dd/yyyy vs. dd.mm.yyyy

Number Example: 3,200.00 vs. 3.200,00

Additionally, it translates month names to the proper language.

Localization will not translate the currency sign used to display money amounts, as this is not dependent on the location, but rather the currency of your data. All currencies are printed using the STX.money method, which can changed as needed based on the currency used at your back office. You can find this function in stx.js.

Supporting multiple locales can be done dynamically since you may set the locale for the chart at any time by calling STX.I18N.setLocale. See STX.I18N.setLocale for more details.

Example:

var stxx=new STXChart();
STX.I18N.setLocale(stxx, "ru"); // Set the chart to Russian dates, numbers and month formats.

Localization is supported through the Intl object which is a W3 standard, however not all browsers support Intl natively. For those browsers, the Intl.js polyfill is included through the inclusion of stxThirdParty.js; which requires the installation of localization objects. The library will automatically determine is the polyfill is required and attempt to load localization data from your web server.

Installing localization data for use with polyfill

Download, unzip and place the localization library in your server. The download site is http://connect2.chartiq.com/locale-data. The extracted data must be placed in a sub-directory within your web server root directory called locale-data

The zip file contains the localization data in both PSON and PSONP format. Our library only utilizes the PSONP format (/locale-data/jsonp/).

As a locale is set or changed, the STX.I18N.setLocale function looks for the appropriate locale file in /locale-data/jsonp/**your_location_code**.js. For example: "locale-data/jsonp/en.js" will be loaded when setting the locale to English.

Failure to properly install the required localization objects will generate the following error: "No locale data has been provided for this object yet."

Translation

Translation services are used to display your menus and built-in chart tags and messages in other languages.

translations.js is required in order to execute the ranslation services.

Be sure to include the following include line in your html file:

<script src="js/translations.js?2"></script>

In there you will find the following 2 elements:

STX.I18N.wordLists[] which holds all English words requiring translation.

STX.I18N.csv which holds all the translations for the supported languages.

You must keep both these lists up to date to ensure all wording is translated. To facilitate in this process, we have included the STX.I18N.printableMissingWordList convenience function. This tool will parse through your UI and find all text elements that are untranslated for the the given language. The output will be a human readable JSON object suitable for delivery to a translator. You must run this function for each language individually.

The CSV file is in the following format (add more languages and words as needed):

!en,            language-2,         language-3,         language-4,         language-5
english-word1,  language-2-word1,   language-3-word1,   language-4-word1,   language-5-word1
english-word2,  language-2-word2,   language-3-word2,   language-4-word2,   language-5-word2
english-word3,  language-2-word3,   language-3-word3,   language-4-word3,   language-5-word3

CSV Example:

!en,ar,fr,de,hu
Chart,الرسم البياني,Graphique,Darstellung,Diagram
Chart Style,أسلوب الرسم البياني,Style de graphique,Darstellungsstil,Diagram stílusa
Candle,الشموع,Bougie,Kerze,Gyertya
Bar,الأعمدة,Barre,Balken,Sáv

Note: Make sure there are no leading tabs, trailing commas or spaces on the CSV file.

Once you have set up your list of English words and corresponding translations, all you have to do is set your language as follows:

var stxx=new STXChart();
STX.I18N.setLanguage(stxx, "ru");

Note: Anything you don't want translated you can remove from the STX.I18N.wordLists. A good example is numbers. If you want to continue to display traditional numbers (1,2,3,4....), but translate all the words, jut remove them form the list and they will not be translated.

Complete Localization example

Localization and language can be hard coded, or you can implement a process for allowing users to select their own language at any time, including local format for prices and dates.

The following code sample illustrates how to use a query string in the url to set the language. This could be used if your web site allowed users to click on a link or button to pop-up a new chart window.

The calling ULR would resemble something like this: https://IQcharts.mywebsite.com/?language=en

This sample can be modified to allow the user to change the language form a menu if desired. You can put this code in your main HTML page used to render the charts.

var qsParm=STX.qs();                                    // first, get the query string form the window

var langCode=qsParm["language"];                         // this must be a valid language code such as en, de, zh, it, pu, etc.

if(langCode){
    STX.I18N.setLanguage(stxx, langCode);                // set the language for the chart
    STX.I18N.setLocale(stxx, langCode);                    // set locale in order to localize dates and numbers.
    //console.log(JSON.stringify(STX.I18N.wordLists.en));    // will list all the words currently being translated
    //console.log(STX.I18N.printableMissingWordList());    // use this to list any words that are missing from your wordLists
}