API Reference
Namespaces
Classes
Events
Global
Externals

Namespace: I18N

CIQ. I18N

Namespace for Internationalization API. See Localization for more details.

Members

langConversionMap :object

A map of language codes to language-region codes for backward compatibility.

The following locale / language-region codes are supported in the examples/translations/translationSample.js file:

  • en: "en-US"
  • ar: "ar-EG"
  • fr: "fr-FR"
  • de: "de-DE"
  • hu: "hu-HU"
  • it: "it-IT"
  • pt: "pt-PT"
  • ru: "ru-RU"
  • es: "es-ES"
  • zh: "zh-CN"
  • ja: "ja-JP"

You can add code mappings as follows:

CIQ.I18N.langConversionMap.ko = "ko-KR";

You can remove unsupported codes by deleting the mappings from this object or by redefining the object with only the languages and regions you choose to support.

Type:
  • object
Since:

  • 8.3.0

language :string

The local language.

Type:
  • string
Default Value:
  • "en"

languages :object

A map of language codes to edonyms (language names in the mapped language). Can be used as a data source for UI components, such as a language picker.

The following languages are predefined:

  • en: "English"

The following additional languages are supported in the examples/translations/translationSample.js file:

  • "en-US": "English",
  • "ar-EG": "عربى",
  • "fr-FR": "Français",
  • "de-DE": "Deutsche",
  • "hu-HU": "Magyar",
  • "it-IT": "Italiano",
  • "pt-PT": "Português",
  • "ru-RU": "русский",
  • "es-ES": "Español",
  • "zh-CN": "中文",
  • "ja-JP": "日本語"

You can add language mappings as follows:

CIQ.I18N.languages.ko = "한국어";

You can remove unsupported languages by deleting the mappings from this object or by redefining the object with only the languages you choose to support.

Type:
  • object
Default Value:
  • { en: "English" }

longMonths :object

The list of languages that don't support shortening the local representation of the month portion of the date.

Customize this property by redefining the list of languages. See the example below.

Type:
  • object
Default Value:
  • { zh: true }
Example
CIQ.I18N.longMonths = {
	"zh-CN": true,
};

reverseColorsByLocale :object

The list of locales used by CIQ.I18N.setLocale to determine whether the up/down colors of candles should be reversed.

Customize this property by redefining the list of locales. See the example below.

Type:
  • object
Since:

  • 4.0.0

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

wordLists :object

A list of word translations for one or more languages.

CIQ.I18N.convertCSV assigns an object to this property based on a CSV-formatted string. You can also set a value explicitly without using CIQ.I18N.convertCSV or CIQ.I18N.setLanguage (see the example below).

Type:
  • object
Default Value:
  • { en: {} }
Example

Word translations for Arabic and Spanish.

// Setting explicitly without using CIQ.I18N.convertCSV or CIQ.I18N.setLanguage.
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

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);

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

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

localize(stx, locale)

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

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,
});

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

printableMissingWordList( [language])

A convenience function for creating a JSON object containing words from CIQ.I18N.missingWordList.

Parameters:
Name Type Argument Default Description
language string <optional>
 CIQ.I18N.language

The language for which words in CIQ.I18N.missingWordList are included in the JSON object.
Returns:

The list of of missing words.

Type
string

reverseCandles(stx)

Reverses the up/down candle colors, as preferred by some locales.

Reverses the colors without changing the CSS.

Parameters:
Name Type Description
stx CIQ.ChartEngine

A reference to the chart engine.
Since:

  • 4.0.0

setLanguage(stx, language [, translationCallback] [, csv] [, root])

Convenience function to set up translation services for a chart and its surrounding GUI. 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 translationSample.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 in translationSample.js.
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 the string contains no leading tabs, trailing commas, or spaces. Default is CIQ.I18N.csv in translationSample.js. See CIQ.I18N.convertCSV for a format sample.
root HTMLElement <optional>

Root element from which to start translating. If the parameter is omitted, the chart UI context is checked for its top node before defaulting to document.body.
Since:
  • 04-2015
  • 3.0.0 Added root parameter.
  • 4.0.0 Language code for Portuguese is "pt" (formerly "pu"; maintained for backwards compatibility).
  • 8.2.0 If no root parameter, the chart UI context is checked for its top node before defaulting to document.body.

setLocale(stx, locale [, cb] [, url] [, maxDecimals])

This method will set the chart locale and check to see if candle colors should be reversed.

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.

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

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,
});

translate(word [, language])

Translates an individual word for a given language using CIQ.I18N.wordLists.

Set stxx.translationCallback to this function to automatically translate all textual elements on the chart.

Parameters:
Name Type Argument Default Description
word string

The word to translate. To be translated, the word must be a property of the object in CIQ.I18N.wordLists specified by language (see the example below).
language string <optional>
 CIQ.I18N.language

The language to which the word is translated. Identifies a property in CIQ.I18N.wordLists.
Returns:

The translation of word, or the value of word if no translation is found.

Type
string
Example

Translate to Spanish

CIQ.I18N.wordLists = {
	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",
	},
};
CIQ.I18N.translate("1 Hour", "es"); // "1 Hora"

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

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 Default Description
language string <optional>
 CIQ.I18N.language

The language into which the UI text is translated.
root HTMLElement <optional>
 document.body

Root node for the DOM tree walker to prevent the entire page from being translated.
Since:

  • 4.0.0 Language code for Portuguese is now "pt" (formerly "pu", which is supported for backward compatibility).