Tutorials
Getting started
Chart interface
Web components
Chart internals
Data integration
Customization
Frameworks and bundlers
Mobile development
Plug-ins
Troubleshooting
Glossary
Reference
JSFiddles

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 two considerations:

1. Dates and 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.

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.

Time zones, although related, are not part of the localization methods. The chart automatically displays x-axis labels in the user's local time zone (the time zone of their operating system/browser). This is because a user may want to see particular data in their local time zone, the time zone of the exchange, or another arbitrary time zone as they see fit. To this end, users can set their preferred time zone regardless of the active locale by using the time zone widget provided in the sample templates, or developers can override this behavior by explicitly setting a time zone. See the Dates, Times, and Time Zones tutorial.

Dates and 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 a French-speaking 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: document.querySelector(".chartContainer"),
	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. If other languages are needed they must be provided.

The library includes sample translations in examples\translations\translationSample.js for the following languages:

  • Arabic (ar)
  • French (fr)
  • German (de)
  • Hungarian (hu)
  • Italian (it)
  • Portuguese (pu)
  • Russian (ru)
  • Spanish (es)
  • Simplified Chinese (zh)
  • Japanese (ja)

This file is included by default, and it also provides other convenience methods to facilitate translations.

Please note that the translations in the examples file do not include every word in the UI. They must be reviewed along with all other methods in that file, and updated as needed to reflect requirements for your particular implementation and UI.

Sidebar: Default translations format and alternate loading methods

Instead of using the CIQ.I18N.hereDoc method to convert the embedded CSV string to a usable string for in CIQ.I18N.setLanguage as done in translationSample.js, you can explicitly call CIQ.I18N.setLanguage with a CSV-formatted string. See CIQ.I18N.convertCSV for a format sample and details.

You can also create a JSON object of translations and directly load them into the chart. To do that, first set CIQ.I18N.csv to null, then set CIQ.I18N.languages to the list of supported languages, and finally set CIQ.I18N.wordLists to the proper translation words as follows:

CIQ.I18N.csv = null;
CIQ.I18N.languages = {
	"en-US": "English",
	"ar-EG": "عربى"
 };
 CIQ.I18N.wordLists = {
     "ar-EG": {
         "1 D": "1ي",
         "1 Hour": "1 ساعة",
         "1 Min": "1د",
         "1 Mo": "1ش",
         "1 W": "أ1",
         "1 hour": "ساعة واحدة",
         "1d": "1يوم",
         "1m": "1شهر",
         "1y": "1عام",
         "3m": "3أشهر"
     }
 };
 CIQ.I18N.language = "en-US";

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 translationSample.js for an 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.makeTranslatableElement 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

Localization for server-side implementations

Although the current Node.js version is Locale-sensitive by default, it is important to note that if you are planning on running the library server side, Node.js only supports English locale and require a polyfill for any other locale.

Using a polyfill service will manage this issue automatically. You can even set it up to return the specific set of locale data you want to use in your implementation by simply adding the list as a query string. For example:

https://cdn.polyfill.io/v3/polyfill.js?features=Intl.~locale.fr,Intl.~locale.pt

If on the other hand you want to manually include the Intl polyfill library into your project, you can use https://www.npmjs.com/package/intl. Remember to also install the required database on your server.

The database can be downloaded here: locale-data.zip

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

Example JSONP Request from Intl :

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 Intl object will load the locale 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