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. 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:
- 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. 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 todocument.body
.
-
<static> 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, });
-
<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).