Library Documentation

Namespace: I18N

CIQ. I18N

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> 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. Note that in the current Intl.js locale, chinese and japanese months are implemented as 1月 through 12月 which causes this algorithm to fail. Hopefully real months will be available when Intl becomes a browser standard, otherwise this method or the locale will need to be modified for those or other special cases. 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:

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, & 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.

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.

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 'root' parameter added.
    • 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. All major browsers now include Intl by default. Firms wishing to support clients with older browsers, can manually load Intl objects instead for the required locales. See tutorial Localization for more details on how to manually load this data.

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", hour12:false});
  • stxx.internationalizer.hourMinuteSecond=new Intl.DateTimeFormat(this.locale, {hour:"numeric", minute:"numeric", second:"numeric", hour12:false});
  • 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 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 maxDecimals was added to the signature
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)