Namespace for Internationalization API. See Localization for more details.
Members
-
csv :string
-
Where we can store a translation spreadsheet in csv format as a single long string.
Type:
- string
-
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 endonyms (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
// 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 have their containing elements converted by this function to accommodate easy translation back and forth between languages.
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.makeTranslatableElement 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});
-
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.makeTranslatableElement 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 todocument.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 ofword
if no translation is found.- Type
- string
Example
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.makeTranslatableElement 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:
-
9.1.0 Translates aria-labels. Aria-label translations do not cross Shadow DOM borders.