# i18n ## Overview The `i18n` object provides a comprehensive API for internationalization, supporting locale-specific settings, message formatting, and time zone management. ## Functionality ### Locale and Localization * Retrieve current locale settings such as country (`getCurrentCountry`), language (`getCurrentLanguage`), and timezone (`getCurrentTimeZone`). * Modify locale settings dynamically using `setLocale(language, country)` or with private extensions. * Retrieve available countries (`getCountries`) and languages (`getLanguages`). ### Message and Format Handling * Retrieve localized messages for keys using `getI18NMessage` with optional dynamic values or specific locale. * Manage formats such as currency (`getCurrencyFormat`), date (`getDateFormat`, `getDefaultDateFormat`), and numbers (`getNumberFormat`, `getDefaultNumberFormat`). ### Time Zones * Get lists of available time zones (`getTimeZones`) and specific offsets (`getTimeZoneOffset`). * Set custom time zone IDs or configurations for precise internationalization needs. ### System Messages and Configuration * Retrieve system-level internationalization messages (`getSystemMessages`). * Customize the first day of the week for calendars (`setFirstDayOfTheWeek`). ## Methods Summarized | Type | Name | Summary | | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) | [getAvailableTimeZoneIDs()](#getavailabletimezoneids) | Get the list of available time zones. | | [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) | [getCountries()](#getcountries) | Gets the list of countries available for localization | | [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) | [getCurrencyFormat()](#getcurrencyformat) | Gets the currency format from client (using client's locale). | | [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) | [getCurrentCountry()](#getcurrentcountry) | Gets the current country; based on the current locale settings in the Servoy Client Locale preferences. | | [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) | [getCurrentExtensions()](#getcurrentextensions) | Gets the current private extensions; based on the current locale settings in the Servoy Client Locale preferences. | | [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) | [getCurrentLanguage()](#getcurrentlanguage) | Gets the current language; based on the current locale settings in the Servoy Client Locale preferences. | | [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) | [getCurrentTimeZone()](#getcurrenttimezone) | Gets the current time zone given by the browser (if it is possible to obtain it). | | [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) | [getDateFormat()](#getdateformat) | Gets the date format from client (using client's locale). | | [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) | [getDefaultDateFormat()](#getdefaultdateformat) | Gets the current default date format from server; based on the current admin settings. | | [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) | [getDefaultNumberFormat()](#getdefaultnumberformat) | Gets the current default number format from server; based on the current admin settings. | | [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) | [getI18NMessage(i18nKey)](#geti18nmessage-i18nkey) | Gets the real message (for the clients locale) for a specified message key. | | [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) | [getI18NMessage(i18nKey, dynamicValues)](#geti18nmessage-i18nkey-dynamicvalues) | Gets the real message (for the clients locale) for a specified message key. | | [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) | [getI18NMessage(i18nKey, dynamicValues, language, country)](#geti18nmessage-i18nkey-dynamicvalues-language-country) | Gets the real message using specified locale for a specified message key. | | [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) | [getI18NMessage(i18nKey, language, country)](#geti18nmessage-i18nkey-language-country) | Gets the real message using the specified locale for a specified message key. | | [JSDataSet](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsdataset) | [getLanguages()](#getlanguages) | Returns a dataset with rows that contains a language key (en) and the displayname (English) column. | | [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) | [getNumberFormat()](#getnumberformat) | Gets the number format from client (using client's locale). | | [JSDataSet](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsdataset) | [getSystemMessages()](#getsystemmessages) | Returns a dataset with rows that contains 3 columns: 'key' (i18n key), 'reference' (reference text for that key) and 'locale (\[CURRENT\_LOCALE])' (where \[CURRENT\_LOCALE] is the current language) - with the system messages of servoy. | | [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) | [getTimeZoneOffset(timeZoneId)](#gettimezoneoffset-timezoneid) | Returns the offset (in milliseconds) of this time zone from UTC for the current date or at the specified date. | | [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) | [getTimeZoneOffset(timeZoneId, date)](#gettimezoneoffset-timezoneid-date) | Returns the offset (in milliseconds) of this time zone from UTC for the current date or at the specified date. | | [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) | [getTimeZones()](#gettimezones) | Returns an array of known timezones. | | void | [setFirstDayOfTheWeek(weekday)](#setfirstdayoftheweek-weekday) | This function overrides the default value of the locale first day of the week property. | | void | [setI18NMessage(i18nKey, value)](#seti18nmessage-i18nkey-value) | Sets the value of i18n key for client scope,if value null the setting is removed. | | void | [setLocale(language, country)](#setlocale-language-country) | Set/Overwrite the locale for this client. | | void | [setLocale(language, country, extensions)](#setlocale-language-country-extensions) | Set/Overwrite the locale for this client. | ## Methods Detailed ### getAvailableTimeZoneIDs() Get the list of available time zones. **Returns:** [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) An array of Strings containing the available time zones. **Sample** ```js //Get the list of available time zones var timezones = i18n.getAvailableTimeZoneIDs(); ``` ### getCountries() Gets the list of countries available for localization **Returns:** [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) a String array containing the available countries. **Sample** ```js i18n.getCountries() ``` ### getCurrencyFormat() Gets the currency format from client (using client's locale). **Returns:** [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) a String representing the currency format. **Sample** ```js var currencyFormat = i18n.getCurrencyFormat(); ``` ### getCurrentCountry() Gets the current country; based on the current locale settings in the Servoy Client Locale preferences. NOTE: For more information on i18n, see the chapter on Internationalization in the Servoy Developer User's Guide, and the chapter on Internationalization-I18N in the Programming Guide. **Returns:** [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) a String representing the current country. **Sample** ```js var currCountry = i18n.getCurrentCountry(); ``` ### getCurrentExtensions() Gets the current private extensions; based on the current locale settings in the Servoy Client Locale preferences. NOTE: For more information on i18n, see the chapter on Internationalization in the Servoy Developer User's Guide, and the chapter on Internationalization-I18N in the Programming Guide. **Returns:** [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) an array of Strings representing the current extensions. **Sample** ```js var currentExtensions = i18n.getCurrentExtensions(); ``` ### getCurrentLanguage() Gets the current language; based on the current locale settings in the Servoy Client Locale preferences. NOTE: For more information on i18n, see the chapter on Internationalization in the Servoy Developer User's Guide, and the chapter on Internationalization-I18N in the Programming Guide. **Returns:** [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) a String representing the current language. **Sample** ```js var currLang = i18n.getCurrentLanguage(); ``` ### getCurrentTimeZone() Gets the current time zone given by the browser (if it is possible to obtain it). **Returns:** [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) a String representing the current time zone. **Sample** ```js var currTimeZone = i18n.getCurrentTimeZone(); ``` ### getDateFormat() Gets the date format from client (using client's locale). **Returns:** [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) a String representing the date format. **Sample** ```js var dateFormat = i18n.getDateFormat(); ``` ### getDefaultDateFormat() Gets the current default date format from server; based on the current admin settings. **Returns:** [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) a String representing the default date format. **Sample** ```js var defaultDateFormat = i18n.getDefaultDateFormat(); ``` ### getDefaultNumberFormat() Gets the current default number format from server; based on the current admin settings. **Returns:** [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) a String representing the default number format. **Sample** ```js var defaultNumberFormat = i18n.getDefaultNumberFormat(); ``` ### getI18NMessage(i18nKey) Gets the real message (for the clients locale) for a specified message key. **Parameters** * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **i18nKey** The message key **Returns:** [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) a String that is the message for the message key. **Sample** ```js // returns 'Welcome my_name in my solution' // if the key 'mykey.username.text' is 'Welcome {0} in my solution' i18n.getI18NMessage('mykey.username.text',new Array('my_name')) ``` ### getI18NMessage(i18nKey, dynamicValues) Gets the real message (for the clients locale) for a specified message key.\ You can use parameter substitution by using {n}, where n is a index number of the value thats in the arguments array. **Parameters** * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **i18nKey** The message key * [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) **dynamicValues** Arguments array when using parameter substitution. **Returns:** [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) a String that is the message for the message key. **Sample** ```js // returns 'Welcome my_name in my solution' // if the key 'mykey.username.text' is 'Welcome {0} in my solution' i18n.getI18NMessage('mykey.username.text',new Array('my_name')) ``` ### getI18NMessage(i18nKey, dynamicValues, language, country) Gets the real message using specified locale for a specified message key.\ You can use parameter substitution by using {n}, where n is a index number of the value thats in the arguments array. **Parameters** * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **i18nKey** The message key * [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) **dynamicValues** Arguments array when using parameter substitution. * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **language** The lowercase 2 letter code of the locale * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **country** The upper case 2 letter code of the locale **Returns:** [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) a String that is the message for the message key. **Sample** ```js // returns 'Welcome my_name in my solution' // if the key 'mykey.username.text' is 'Welcome {0} in my solution' i18n.getI18NMessage('mykey.username.text',new Array('my_name'),'en','US') ``` ### getI18NMessage(i18nKey, language, country) Gets the real message using the specified locale for a specified message key. **Parameters** * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **i18nKey** The message key * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **language** The lowercase 2 letter code of the locale * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **country** The upper case 2 letter code of the locale **Returns:** [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) a String that is the message for the message key. **Sample** ```js // returns 'Welcome my_name in my solution' // if the key 'mykey.username.text' is 'Welcome {0} in my solution' i18n.getI18NMessage('mykey.username.text',new Array('my_name'),'en','US') ``` ### getLanguages() Returns a dataset with rows that contains a language key (en) and the displayname (English) column. See for a list that could be returned. **Returns:** [JSDataSet](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsdataset) a JSDataSet with all the languages. **Sample** ```js var set = i18n.getLanguages(); for(var i=1;i<=set.getMaxRowIndex();i++) { application.output(set.getValue(i, 1) + " " + set.getValue(i, 2)); } ``` ### getNumberFormat() Gets the number format from client (using client's locale). **Returns:** [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) a String representing the number format. **Sample** ```js var numberFormat = i18n.getNumberFormat(); ``` ### getSystemMessages() Returns a dataset with rows that contains 3 columns: 'key' (i18n key), 'reference' (reference text for that key) and 'locale (\[CURRENT\_LOCALE])' (where \[CURRENT\_LOCALE] is the current language) - with the system messages of servoy.\ This means all servoy messages, with all available translations. **Returns:** [JSDataSet](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsdataset) a JSDataSet with all the system messages. **Sample** ```js var set = i18n.getSystemMessages(); for(var i=1;i<=set.getMaxRowIndex();i++) { application.output(set.getValue(i, 1) + " " + set.getValue(i, 2)+ " " + set.getValue(i, 3)); } ``` ### getTimeZoneOffset(timeZoneId) Returns the offset (in milliseconds) of this time zone from UTC for the current date or at the specified date. **Parameters** * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **timeZoneId** The time zone to get the offset for. **Returns:** [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) an int representing the time zone's offset from UTC. **Sample** ```js var timeZoneOffset = i18n.getTimeZoneOffset('America/Los_Angeles'); ``` ### getTimeZoneOffset(timeZoneId, date) Returns the offset (in milliseconds) of this time zone from UTC for the current date or at the specified date. **Parameters** * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **timeZoneId** The time zone to get the offset for. * [Date](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/date) **date** The date in the time zone (default current date). Needed in case daylight saving time/GMT offset changes are used in the time zone. **Returns:** [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) an int representing the time zone's offset from UTC. **Sample** ```js var timeZoneOffset = i18n.getTimeZoneOffset('America/Los_Angeles'); ``` ### getTimeZones() Returns an array of known timezones. **Returns:** [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) an Array with all the timezones. **Sample** ```js var timeZones = i18n.getTimeZones(); ``` ### setFirstDayOfTheWeek(weekday) This function overrides the default value of the locale first day of the week property.\ This is used in the various calendar fields (default,bootstrap) **Parameters** * [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) **weekday** The weekday that should be shown as the first day (1 == monday) **Returns:** void **Sample** ```js // set the first day of the week to monday even if the locale in the browser (us) says i it is 0 (sunday) i18n.setFirstDayOfTheWeek(1); ``` ### setI18NMessage(i18nKey, value) Sets the value of i18n key for client scope,if value null the setting is removed.\ All forms not yet loaded will change (execute this in solution startup or first form) **Parameters** * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **i18nKey** The message key * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **value** They value for the message key. **Returns:** void **Sample** ```js //sets the value of i18n key for client scope; if value null the setting is removed //Warning: already created form elements with i18n text lookup will not change, //so call this method in the solution startup method or in methods from first form //this method saves message for current locale, so if locale is changed with setLocale, all messages set from scripting will be lost i18n.setI18NMessage('mykey.username.text','my_name') ``` ### setLocale(language, country) Set/Overwrite the locale for this client.\ All forms not yet loaded will change (execute this in solution startup or first form). The language must be a lowercase 2 letter code defined by ISO-639.\ see ISO 639-1 codes at The country must be an upper case 2 letter code defined by ISO-3166\ see ISO-3166-1 codes at NOTE: For more information on i18n, see the chapter on Internationalization in the Servoy Developer User's Guide, and the chapter on Internationalization-I18N in the Programming Guide. **Parameters** * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **language** The lowercase 2 letter code * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **country** The upper case 2 letter code. **Returns:** void **Sample** ```js //Warning: already created form elements with i18n text lookup will not change, //so call this method in the solution startup method or in methods from first form i18n.setLocale('en','US'); ``` ### setLocale(language, country, extensions) Set/Overwrite the locale for this client.\ All forms not yet loaded will change (execute this in solution startup or first form). The language must be a lowercase 2 letter code defined by ISO-639.\ see ISO 639-1 codes at The country must be an upper case 2 letter code defined by ISO-3166\ see ISO-3166-1 codes at The extensions must be an array of strings indicating for example different industries. Each extension string must consist of only letters and digits with a max length of 8 characters\ see private extensions at NOTE: For more information on i18n, see the chapter on Internationalization in the Servoy Developer User's Guide, and the chapter on Internationalization-I18N in the Programming Guide. **Parameters** * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **language** The lowercase 2 letter code * [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **country** The upper case 2 letter code * [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) **extensions** array of private extensions strings **Returns:** void **Sample** ```js //Warning: already created form elements with i18n text lookup will not change, //so call this method in the solution startup method or in methods from first form i18n.setLocale('en','US'); ``` ***