Localization

The charting library can display dates, numbers and words in the native format for any country. "Localizing" is the process of configuring an application for a particular country.

When localizing a chart, there are three considerations:

1. Dates & Numbers: Dates appear along the x-axis. Numbers appear along the y-axis. The chart's "locale" determines the formatting of values on either axis (for instance, whether to use commas or decimal points in prices on the y-axis).

2. Translation: Charting elements (canvas) and the UI that surrounds the chart (DOM) contain English text but can be switched to other languages.

3. Timezones: The chart automatically displays x-axis labels in the user's local time zone (the time zone of their operating system/browser). Developers can override this behavior by explicitly setting a time zone. See Dates & Timezones.

The default language and locale for the charting library is English ("en"). Developers can change the language and locale for the chart programmatically to suit their particular clientele.

Dates & Numbers

Use CIQ.I18N.setLocale to change the locale of the chart. This will automatically format dates (x-axis) and numbers (y-axis) into the proper format for the country. You can use any locale supported by the W3 Intl standard; for instance, "fr" for France and "de-AT" for German as used in Austria.

Example, set chart to French-speaking France locale :

CIQ.I18N.setLocale(stxx, "fr-FR");

Chart showing France Locale

After setting to the "fr-FR" locale, the x-axis shows dates in YY/MM/DD format. The y-axis numbers have commas instead of periods.

You can even use the locale to change between a 24 hour display to a 12 hour display as follows:

var stxx=new CIQ.ChartEngine({container:$("#chartContainer")[0], preferences:{labels:false, currentPriceLine:true, whitespace:0}});

CIQ.I18N.setLocale(stxx, "en");    // set localization services -- before any UI or chart initialization is done
// override time formatting to enable 12 hour clock (hour12:true)
stxx.internationalizer.hourMinute=new Intl.DateTimeFormat(this.locale, {hour:"numeric", minute:"numeric", hour12:true});
stxx.internationalizer.hourMinuteSecond=new Intl.DateTimeFormat(this.locale, {hour:"numeric", minute:"numeric", second:"numeric", hour12:true});

This will display times in AM/PM format, such as 2:30 PM or 9:15 AM.

Translation

English is the default language for the chart. The SDK includes translations for the following languages: Arabic (ar), French (fr), German (de), Hungarian (hu), Italian (it), Portuguese (pu), Russian (ru), Spanish (es), Simplified Chinese (zh) and Japanese (ja). To switch to another language, you must include the translations.js file.

Sidebar: Default translations format and alternate loading methods

since minifying translations.js would destroy the CIQ.I18N.hereDoc comment that holds the csv copy-paste, it is best to bundle this file separately. If using UglifyJS, you can specify this filename in the except array to exclude it from compression. Alternatively, instead of using the CIQ.I18N.hereDoc method to convert the copy-paste csv file in translations.js to a usable string for CIQ.I18N.setLanguage, you can explicitly call CIQ.I18N.setLanguage with a 'csv formatted' string. See CIQ.I18N.convertCSV for format sample and details. You can also Create a JSON object of translations, set CIQ.I18N.wordLists to it and modify CIQ.I18N.setLanguage to just use CIQ.I18N.wordLists :

 CIQ.I18N.setLanguage=function(stx, language, translationCallback, csv, root){
  //CIQ.I18N.convertCSV(csv);  // remove this line and instead add this new line:
  CIQ.I18N.wordLists = your JSON object here;
  CIQ.I18N.language=language;
  CIQ.I18N.translateUI(language, root);
  if (!translationCallback) translationCallback = CIQ.I18N.translate;
  stx.translationCallback=translationCallback;
 };

Call CIQ.I18N.setLanguage to switch to another language.

Example, translate the chart to Chinese :

CIQ.I18N.setLanguage(stxx, "zh");

Chart translated to Chinese

This chart has been translated to Chinese. Note that the axis have not changed. Axis are controlled by "locale" not translation.

Translating inside your JS code.

To explicitly translate new words or phrases being generated real time by your javaScript code, you should use CIQ.ChartEngine#translateIf. This will ensure they are also translated, even if added to the DOM after CIQ.I18N.translateUI was executed.

Creating Additional Translations

If you have customized the chart (or the user interface surrounding the chart), you've probably added new phrases that require translation. Simply add additional translation phrases to the source (CIQ.I18N.hereDoc is the default)

Please note the special csv formatting. There must not be any indenting on the left side. See translations.js for example.

Partial phrases will not be translated.

It is not necessary to include a translation phrase for every language. If you don't have a translation, don't put anything between the two commas (...ACTIONS,AKTIEN,,AZIONI,...). The translation will be bypassed (leaving the English default).

Sidebar: Understanding How Translation Affects the DOM

CIQ.I18N.setLanguage calls the function CIQ.I18N.translateUI to translate DOM elements. Every DOM text node is checked for a matching translation (from English to the desired language). If a match is found, the text node is replaced with a <translate> tag. That tag is filled with the newly translated text. The original English text is moved to an attribute called "original."

Example, translation changes the DOM :

Before translation:
<div>STOCK</div>

After translation:
<div><translate original="STOCK">股票</translate></div>

Reversing colors depending on language

Some localizations such as 'Chinese', may also require that colors for up-ticks and down-ticks be reversed (red for up and green for down). This is also possible by using the CIQ.I18N.localize convenience function.

Notes

Where to Put This Code

localize(), setLocale() and setLanguage() should be called after your chart engine (CIQ.ChartEngine) is created. Once your engine is created, these methods can be called again to dynamically switch between languages. For example, you may want to build a menu so that users can switch between languages. Your menu would send the user's selected language code to localize(), setLocale() or setLanguage().

It is important to note that if you are dynamically creating UI content and adding it to the DOM after you have set the language, you must either call CIQ.I18N.translateUI after the new content is added, or ensure your code explicitly translates the new content using CIQ.translatableTextNode or CIQ.ChartEngine#translateIf.

Bypassing UI Translation

CIQ.I18N.setLanguage will automatically translate the entire page (not just the chart). You can override the CIQ.I18N.translateUI method to bypass translation of DOM nodes.

Example, Preventing translation of DOM :

CIQ.I18N.translateUI=function(){}; // override to do nothing

Currency Formatting

Charts do not display currencies on the y-axis, but currencies are used in the Trade From Chart (TFC) plugin. TFC uses CIQ.convertCurrencyCode and CIQ.money to display currency codes and to format money.

Example, Displaying currencies :

CIQ.convertCurrencyCode("JPY");
result: "¥"

CIQ.money(1,null,"GBP");
result: £1.00

Intl.js

The Intl library is native to all modern browsers except Safari (verion 9 or lower an mobile). To support Safari, you must include the Intl.js polyfill (included in the js directory). This polyfill depends on a locale database that must be installed on your webserver. The database can be downloaded here:

http://connect2.chartiq.com/locale-data.zip

Unzip and install onto your webserver and into a directory called "locale-data." Whenever CIQ.I18N.setLocale is called, the polyfill will make a JSONP request to your webserver to load the locale configuration.

Example, Example JSONP Request from Intl polyfill :

https://yourdomain.com/locale-data/jsonp/fr.js

If the database is not installed correctly, you will see the following error in the browser console:

"No locale data has been provided for this object yet."

Check the network tab in your browser debugger to see the JSONP request. This will help you reconfigure your webserver.

Important Note: The polyfill will load the jsonp files for you. Do not bundle these files into your application because the native Intl in most browsers will not recognize these files and will result in console errors.


Next Steps: