Intermediate

Components Localization

Different countries and regions have their own rules for writing dates, numbers, monetary units and text labels. All these issues should be taken in account in case the target group for your application is wider than one country or region.

The set of rules for this or that country is called a locale and includes methods for date, time, number, price and label formatting. Localization methods belong to the i18n class and treat data according to the set format.

By default, the Date() constructor outputs raw data. Unformatted, it looks barely readable.

new Date(2010,10,30); //-->Tue Nov 30 2010 00:00:00

Date and time should be formatted either with Date or the i18n class.

The complete list of Date formatting methods and supported format options.

Decimal and integer numbers are displayed with different delimiters, depending on the rules of a particular country. Prices should be rendered with appropriate currency marks.

Formatting is done either in the Number or the i18n class.

Built-in Locales

The standard package of the Webix library includes 10 locales, namely:

  • "en-US" - North American (used by default);
  • "ru-RU" - Russian;
  • "fr-FR" - French;
  • "ja-JP" - Japanese;
  • "be-BY" - Belarusian;
  • "de-DE" - German;
  • "es-ES" - Spanish;
  • "it-IT" - Italian;
  • "zh-CN" - Chinese;
  • "pt-BR" - Portuguese (Brazil).

Webix Pro edition includes over 300 locales.

Locale Structure

The way formatted data is presented depends on the locale you use. A locale is a set of rules for dates, numbers, price units and labels for this or that region or country. By default the en-US locale is used.

en-US Locale

webix.i18n.locales["en-US"]={
  groupDelimiter:",",
  groupSize:3,
  decimalDelimiter:".",
  decimalSize:2,
 
  dateFormat:"%m/%d/%Y",
  timeFormat:"%h:%i %A",
  longDateFormat:"%d %F %Y",
  fullDateFormat:"%m/%d/%Y %h:%i %A",
  am:["am","AM"],
  pm:["pm","PM"],
 
  price:"${obj}",
  priceSettings:{
    groupDelimiter:",",
    groupSize:3,
    decimalDelimiter:".",
    decimalSize:2
  },
 
  fileSize: ["b","Kb","Mb","Gb","Tb","Pb","Eb"],
 
  calendar: {
    monthFull:[
      "January", "February", "March", "April", "May", "June", "July", 
      "August", "September", "October", "November", "December"
    ],
    monthShort:[
      "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", 
      "Sep", "Oct", "Nov", "Dec"
    ],
    dayFull:[
      "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday",
      "Friday", "Saturday"
    ],
    dayShort:["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"],
    hours: "Hours",
    minutes: "Minutes",
    done:"Done",
    clear: "Clear",
    today: "Today"
  },
 
  dataExport:{
    page:"Page",
    of:"of"
  },
 
  PDFviewer:{
    of:"of",
    automaticZoom:"Automatic Zoom",
    actualSize:"Actual Size",
    pageFit:"Page Fit",
    pageWidth:"Page Width",
    pageHeight:"Page Height",
    enterPassword:"Enter password",
    passwordError:"Wrong password"
  },
 
  aria:{
    calendar:"Calendar",
    increaseValue:"Increase value",
    decreaseValue:"Decrease value",
    navMonth:["Previous month", "Next month"],
    navYear:["Previous year", "Next year"],
    navDecade:["Previous decade", "Next decade"],
    dateFormat:"%d %F %Y",
    monthFormat:"%F %Y",
    yearFormat:"%Y",
    hourFormat:"Hours: %h %A",
    minuteFormat:"Minutes: %i",
    removeItem:"Remove item",
    pages:["First page", "Previous page", "Next page", "Last page"],
    page:"Page",
    headermenu:"Header menu",
    openGroup:"Open column group",
    closeGroup:"Close column group",
    closeTab:"Close tab",
    showTabs:"Show more tabs",
    resetTreeMap:"Reset tree map",
    navTreeMap:"Level up",
    nextTab:"Next tab",
    prevTab:"Previous tab",
    multitextSection:"Add section",
    multitextextraSection:"Remove section",
    showChart:"Show chart",
    hideChart:"Hide chart",
    resizeChart:"Resize chart"
  },
 
  richtext:{
    underline: "Underline",
    bold: "Bold",
    italic: "Italic"
  },
 
  combo:{
    select:"Select",
    selectAll:"Select all",
    unselectAll:"Unselect all"
  },
 
  message:{
    ok:"OK",
    cancel:"Cancel"
  },
 
  comments:{
    send: "Send",
    confirmMessage: "The comment will be removed. Are you sure?",
    edit: "Edit",
    remove: "Remove",
    placeholder: "Type here..",
    moreComments:"More comments"
  }
};

Numbers:

  • groupDelimiter (string) - a punctuation mark to divide number groups;
  • groupSize (number) - the number of digits in each group. Typically it's equal to 3, since thousands are the most frequent group;
  • decimalDelimiter - a punctuation mark to divide the integer part from the fractional part of a decimal number;
  • decimalSize (number) - the number of digits in the fractional part.

Date and Time:

  • dateFormat, longDateFormat, fullDateFormat - defines the way days, months and years look like in the stated modes;
  • timeFormat - defines the way hours, minutes and seconds look;
  • am,pm - defines the way time before and after noon is marked.

Start Date:

By default, a week in the calendar starts on Sunday. However, you can set any day as a start day using the webix.Date.startOnMonday property

webix.Date.startOnMonday = true;

Price states monetary unit applied to the data from the data object ({obj}).

Calendar:

  • monthFull, dayFull (string) - an array of full and short month names for this location;
  • monthShort, dayShort (string) - an array of full and short day names for this location.

When formatted to a short/long date, the date from the first snippet looks like this:

Formatted with en-US locale

format:webix.i18n.dateFormatStr
    //--> 11/30/2010
 
format:webix.i18n.longDateFormatSt
    // --> 30 November 2010
  • hours, minutes - localization options for 'Hours', 'Minutes' labels in the calendar;
  • today, clear - configuration for "Today" and "Clear" buttons, used for selection of current date and removing selection;
  • done - the text label of the "Done" button.

Controls

Text labels for some parts of Webix components that are more likely to be changed in a scope, such as:

  • select - the text label of the 'Select' button of the multisuggest (used in the multiselect input, editor and filter). The default value for North American locale is "Select".

Data Export

Text labels that are used in the page numbering line in the footer of the exported PDF document include:

  • page - the text label of the "Page" part in the page numbering line;
  • of - the text label of the "of" part in the page numbering line.

PDF Viewer

Text labels for page switching and document options in PDF Viewer are:

  • of - the text label of the "of" part used in the page selector;
  • automaticZoom - the text label of the zooming option for setting the document size automatically;
  • actualSize - the text label of the zooming option for setting actual size of the document;
  • pageFit - the text label of the zooming option for adjusting the document size to the page size;
  • pageWidth - the text label of the zooming option for adjusting the document size to the page width;
  • pageHeight - the text label of the zooming option for adjusting the document size to the page height;
  • enterPassword - the title of the 'password' window header;
  • passwordError - the text of the embedded red highlighting (appears in case of failing the password validation).

Aria

Text labels for widget interactive areas which properties cannot be configured by public API. These labels are set as values of the aria-label attribute and are used by screen reading software to announce the purpose of the element:

  • increaseValue - the aria label for the "+" counter button;
  • decreaseValue - the aria label for the "-" counter button;
  • navMonth - aria labels for the previous and the next month buttons in a calendar;
  • navYear - aria labels for the previous and the next year buttons in a calendar;
  • navDecade - aria labels for the previous and the next decade buttons in a calendar;
  • removeItem - the aria label for the multicombo "x" button;
  • pages - aria labels for pager navigation buttons;
  • page - the aria label for pager numbered buttons;
  • headermenu - the aria label for the headermenu icon in a datatable;
  • openGroup - the aria label for the "+" (open group) icon in a datatable;
  • closeGroup - the aria label for the "-" (close group) icon in a datatable;
  • closeTab - the aria label for the "x" icon on a closable tab in a tabbar;
  • showTabs - the aria label for the "show more tabs" icon in a responsive tabbar;
  • resetTreeMap - the aria label for the "reset tree map" icon in a zoomed-in treemap;
  • navTreeMap - the aria label for the "level up" icon in a zoomed-in treemap;
  • nextTab - the aria label for the ">" icon in the carousel navigation panel;
  • prevTab - the aria label for the "<" icon in the carousel navigation panel;
  • multitextSection - the aria label for the "+" multitext icon;
  • multitextextraSection - the aria label for the "-" multitext icon;
  • showChart - the aria label for the "show chart" button in the chart legend;
  • showChart - the aria label for the "hide chart" button in the chart legend;
  • resizeChart - the aria label for the rangechart sizing handle.

RichText

Text labels for the font style buttons in the RichText control are:

  • underline - the text label of the "Underline" button;
  • bold - the text label of the "Bold" button;
  • italic - the text label of the "Italic" button.

Combo

Text labels for the buttons used for selecting/unselecting items are:

  • select - the name of a button for selecting an item;
  • selectAll - the name of the button state for selecting all items;
  • unselectAll - the name of the button state for unselecting all items.

Message

Text labels for the buttons used in the modal message boxes are:

  • ok - the text label of the "OK" button;
  • cancel - the text label of the "Cancel" button.

Comments

Text labels for the buttons and context menu used in the Comments widget are:

  • send - the text label of the sending comments button;
  • confirmMessage - the text in the body of the confirmation box;
  • edit - the text label of the "Edit" button;
  • remove - the text label of the "Remove" button;
  • placeholder - the text of the placeholder;
  • moreComments - the text label of the "More comments" button.

Applying a Locale

Locales other than en-US should be set manually.

You should apply the chosen locale with the help of the setLocale() function that takes the locale name as a parameter.

webix.i18n.setLocale("fr-FR");

After this, any method applied to the webix.i18n object will redraw date and numbers according to the rules described in the applied locale.

format:webix.i18n.dateFormatStr 
    // --> 30/11/2010
 
format:webix.i18n.longDateFormatStr 
    // --> 30 Novembre 2010

Altering a Locale

To change one or several parameters for the current locale, you need to redefine them and then apply the same locale so that your changes come into force:

webix.i18n.fullDateFormat = "%Y-%m-%d %H:%i";
webix.i18n.setLocale(); // locale name is not specified here

Setting Localized i18n Format

Localization is done via the i18n class and allows setting customized formats gathered under one and the same locale.

In case of DataTable, the format is stated by the dedicated format parameter while data is specified by the column ID:

{ header:"Date",  id:"start", format:webix.i18n.dateFormatStr},
{ header:"Price", id:"price", format:webix.i18n.priceFormat}

Related sample:  DataTable Localization

Other components like List, DataView and Tree have quite the other way of data presenting. To ensure proper formatting, you should make use of a template function:

template:function(obj){ 
    return webix.i18n.longDateFormatStr(obj.start)+"<br/>"+
       webix.i18n.priceFormat(obj.price);
}

The format in use is defined by the current locale. The default EN-US locale sets dateFormatStr as "%m/%d/%Y", while the price format is set as "{obj}currency", where obj is the price value.

Related sample:  Dataview Formatting

Back to top