ChartIQ SDK Documentation

Namespace for Internationalization API. See Localization for more details.

Members

<static> language :string

Must be set to the desired language. Defaults to english "en"

Type:

string

<static> languages :Object

This maps country codes to the actual name of the language in that language. This can be used to drive UI, such as a language picker. The following languages are predefined: "en":"English", The following additional languages are supported in the translationSample.js sample translations file: "ar":"عربى", "fr":"Français", "de":"Deutsche", "hu":"Magyar", "it":"Italiano", "pt":"Português", "ru":"русский", "es":"Español", "zh":"中文", "ja":"日本語" You may add additional language as follows: CIQ.I18N.languages.ko="한국어"; You may also remove unsupported languages by deleting them from the object, or redefining this object with the languages you prefer to support.

Type:

Object

<static> longMonths :Object

Sets the languages that that don't support shortening Translation will print entire month from locale for these languages

Type:

Object

<static> reverseColorsByLocale :Object

Maintains the list of locales used by CIQ.I18N.localize to decide if the up/down colors should be reversed and can be updated as outlined on the example.

Defaults to : {"zh":true,"ja":true};

Type:

Object

Since:

4.0.0

Example

CIQ.I18N.reverseColorsByLocale = {
	zh: true,
	ja: true,
	fr: true,
	de: true,
	hu: true,
	it: true,
	pt: true,
};

<static> wordLists :Object

This object will be created by CIQ.I18N.convertCSV based on the provided 'CSV formatted' string, or you can set it explicitly if not using CIQ.I18N.setLanguage or CIQ.I18N.convertCSV

Type:

Object

Example

// sample of object with translations for Arabic and Spanish
( when setting explicitly without using CIQ.I18N.setLanguage or CIQ.I18N.convertCSV )
CIQ.I18N.wordLists={
		"ar":{
			"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أشهر"
		},
		"es":{
			"1 D": "1 D",
			"1 Hour": "1 Hora",
			"1 Min": "1 Min",
			"1 Mo": "1 Mes",
			"1 W": "1 S",
			"1 hour": "1 hora",
			"1d": "1d",
			"1m": "1m",
			"1y": "1a",
			"3m": "3m"
		}
}

Methods

<static> convertCSV( [csv])

Converts a 'CSV formatted' string of translations into the required JSON format and set to CIQ.I18N.wordLists You can output CIQ.I18N.wordLists to the console and paste back in if desired.

Parameters:

Name	Type	Argument	Description
`csv`	string	<optional>	Translation spreadsheet in csv format as a single long string. Make sure there are no leading tabs, trailing commas or spaces. Assumes that the header row of the CSV is the language codes and that the first column is the key language (English). Assumes non-quoted words, data is comma delimited and lines separated by '\n'. Default is CIQ.I18N.csv

Example

var csv =
	"en,ar,fr,de,hu,it,pt,ru,es,zh,ja\nChart,الرسم البياني,Graphique,Darstellung,Diagram,Grafico,Gráfico,График,Gráfica,图表,チャート\nChart Style,أسلوب الرسم البياني,Style de graphique,Darstellungsstil,Diagram stílusa,Stile grafico,Estilo do gráfico,Тип графика,Estilo de gráfica,图表类型,チャート形式\nCandle,الشموع,Bougie,Kerze,Gyertya,Candela,Vela,Свеча,Vela,蜡烛,ローソク足\nShape,شكل,Forme,Form,Alak,Forma,Forma,Форма,Forma,形状,パターン";
CIQ.I18N.convertCSV(csv);

<static> createMonthArrays(stx, formatter, locale)

Extract the name of the month from the locale. We do this by creating a localized date for the first date of each month. Then we extract the alphabetic characters. MonthLetters then becomes the first letter of the month. The arrays are stored in stx.monthAbv and stx.monthLetters which will then override the global arrays CIQ.monthAbv and CIQ.monthLetters.

Parameters:

Name	Type	Description
`stx`	CIQ.ChartEngine	Chart object
`formatter`	object	An Intl compatible date formatter
`locale`	string	A valid Intl locale, such as en-IN

<static> findAllTextNodes( [root])

Returns a word list containing unique words. Each word references an array of DOM nodes that contain that word. This can then be used for translation. Text nodes and placeholders which are found in the document tree will be wrapped by this function within a tag for easy translation back and forth.

Parameters:

Name	Type	Argument	Description
`root`	HTMLElement	<optional>	root for the TreeWalker. If omitted, document.body assumed.

Returns:

A word list containing unique words.

Type: object

<static> localize(stx, locale)

A convenience function that sets locale and language at once and checks to see if candle colors should be reversed. Each of these grouped functions are called with default arguments. If you require custom parameters you will need to call each separately.

CIQ.I18N.reverseColorsByLocale is used to determine if the colors should be reversed.

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.

Functions are called in the following order:

CIQ.I18N.setLocale
CIQ.I18N.setLanguage
CIQ.I18N.reverseCandles - Called only if colors need to be reversed.

Parameters:

Name	Type	Description
`stx`	CIQ.ChartEngine	Chart object
`locale`	string	A valid Intl locale, such as en-IN

Since:

4.0.0

Example

CIQ.I18N.localize(stxx, "zh"); // set translation and 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,
});

<static> missingWordList( [language])

CIQ.I18N.missingWordList will scan the UI by walking all the text elements. It will determine which text elements have not been translated for the given language and return those as a JSON object.

Parameters:

Name	Type	Argument	Description
`language`	string	<optional>	The language to search for missing words. Defaults to whatever language CIQ.I18N.language has set.

Since:

4.0.0 Iterates over the studyLibrary entry name, inputs, and outputs.

Returns:

Words that are undefined with values set to empty strings

Type: object

<static> printableMissingWordList( [language])

A convenient function for creating a human readable JSON object suitable for delivery to a translator.

Parameters:

Name	Type	Argument	Description
`language`	string	<optional>	language. Defaults to CIQ.I18N.language.

Returns:

String of missing words.

Type: string

<static> reverseCandles(stx)

Some locales prefer candle colors reversed. This will reverse candle colors without changing CSS.

Parameters:

Name	Type	Description
`stx`	CIQ.ChartEngine	Chart object

Since:

4.0.0

<static> setLanguage(stx, language [, translationCallback] [, csv] [, root])

Convenience function to set up translation services for a chart and its surrounding GUI. It automatically sets CIQ.I18N.language, loads all translations and translates the chart.

Uses/sets (in execution order):

Feel free to create your own convenience function if required to explicitly set CIQ.I18N.wordLists instead of using the CIQ.I18N.hereDoc copy-paste spreadsheet in translations.js.

Parameters:

Name	Type	Argument	Description
`stx`	CIQ.ChartEngine		A chart object
`language`	string		A language in your CSV file. For instance 'en' from CIQ.I18N.csv
`translationCallback`	string	<optional>	Function to perform Canvas Built-in word translations . Default is CIQ.I18N.translate
`csv`	string	<optional>	Translation spreadsheet in csv format as a single long string. Make sure no leading tabs, trailing commas or spaces. Default is CIQ.I18N.csv. See CIQ.I18N.convertCSV for format sample
`root`	HTMLElement	<optional>	root for the TreeWalker to prevent the entire page from being translated. If omitted, document.body assumed.

Since:

04-2015
3.0.0 Added root parameter.
4.0.0 Language code for Portuguese is "pt" (formerly "pu"; maintained for backwards compatibility).

<static> setLocale(stx, locale [, cb] [, url] [, maxDecimals])

This method will set the chart locale.

If set, display prices and dates will be displayed in localized format. The locale should be a valid IANA locale. For instance de-AT represents German as used in Austria.

Localization in the library is supported through the Intl object which is a W3 standard supported by all modern browsers.

Once a locale is set, stxx.internationalizer will be an object that will contain several Intl formatters.

These are the default date and time formats:

stxx.internationalizer.hourMinute=new Intl.DateTimeFormat(this.locale, {hour:"numeric", minute:"numeric", hourCycle:"h23"});
stxx.internationalizer.hourMinuteSecond=new Intl.DateTimeFormat(this.locale, {hour:"numeric", minute:"numeric", second:"numeric", hourCycle:"h23"});
stxx.internationalizer.mdhm=new Intl.DateTimeFormat(this.locale, {year:"2-digit", month:"2-digit", day:"2-digit", hour:"2-digit", minute:"2-digit"});
stxx.internationalizer.monthDay=new Intl.DateTimeFormat(this.locale, {month:"numeric", day:"numeric"});
stxx.internationalizer.yearMonthDay=new Intl.DateTimeFormat(this.locale, {year:"numeric", month:"numeric", day:"numeric"});
stxx.internationalizer.yearMonth=new Intl.DateTimeFormat(this.locale, {year:"numeric", month:"numeric"});
stxx.internationalizer.month=new Intl.DateTimeFormat(this.locale, {month:"short"});

These can be overridden manually if the specified format is not acceptable. See example. Also see Intl.DateTimeFormat for formatting alternatives

Parameters:

Name	Type	Argument	Description
`stx`	CIQ.ChartEngine		A chart object
`locale`	string		A valid IANA locale, for instance en-IN
`cb`	function	<optional>	Callback when locale has been loaded. This function will be passed an error message if it cannot be loaded.
`url`	string	<optional>	url where to fetch the locale data. Defaults to "locale-data/jsonp". Only used if not natively supported by the browser.
`maxDecimals`	number	<optional>	maximum number of decimal places to allow on number conversions. Defaults to 5. See CIQ.ChartEngine#setLocale for more details.

Since:

3.0.0 Added maxDecimals parameter.

Example

CIQ.I18N.setLocale(stxx, "zh"); // 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,
});

<static> translate(word [, language])

Translates an individual word for a given language. Set stxx.translationCallback to this function in order to automatically translate all textual elements on the chart itself.

Parameters:

Name	Type	Argument	Description
`word`	string		The word to translate
`language`	string	<optional>	language. Defaults to CIQ.I18N.language.

Returns:

Translation of the given word, or the word itself if no translation was found.

Type: string

<static> translateSections(word [, languageWordList])

Translates a phrase which may have untranslatable parts (like a study id). The translatable pieces are delimited left and right with a non-printable character Zero-Width-Non_Joiner.

Parameters:

Name	Type	Argument	Description
`word`	string		The word to translate
`languageWordList`	object	<optional>	Map of words and translations in the desired language

Since:

4.0.0

Returns:

Translation of the given phrase

Type: string

<static> translateUI( [language] [, root])

Passes through the UI (DOM elements) and translates all of the text for the given language.

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 this function again after the new content is added, or ensure your code explicitly translates the new content using CIQ.translatableTextNode or CIQ.ChartEngine#translateIf.

Parameters:

Name	Type	Argument	Description
`language`	string	<optional>	language. Defaults to CIQ.I18N.language.
`root`	HTMLElement	<optional>	root for the TreeWalker to prevent the entire page from being translated. If omitted, document.body assumed.

Since:

4.0.0 Language code for Portuguese is "pt" (formerly "pu"; maintained for backwards compatibility).

Namespace: I18N

Members

<static> language :string

Type:

<static> languages :Object

Type:

<static> longMonths :Object

Type:

<static> reverseColorsByLocale :Object

Type:

Example

<static> wordLists :Object

Type:

Example

Methods

<static> convertCSV( [csv])

Parameters:

Example

<static> createMonthArrays(stx, formatter, locale)

Parameters:

<static> findAllTextNodes( [root])

Parameters:

Returns:

<static> localize(stx, locale)

Parameters:

Example

<static> missingWordList( [language])

Parameters:

Returns:

<static> printableMissingWordList( [language])

Parameters:

Returns:

<static> reverseCandles(stx)

Parameters:

<static> setLanguage(stx, language [, translationCallback] [, csv] [, root])

Parameters:

<static> setLocale(stx, locale [, cb] [, url] [, maxDecimals])

Parameters:

Example

<static> translate(word [, language])

Parameters:

Returns:

<static> translateSections(word [, languageWordList])

Parameters:

Returns:

<static> translateUI( [language] [, root])

Parameters: