Internationalization

ZingGrid has smart defaults for rendering <zg-column> with type number, date, and currency through internationalization. Implementing this feature will enable smart filtering, sorting, searching, and the dir attribute.

Detecting Language/ Locale

English is the default language used for grids, even if <html lang="en"> is not defined. When you define another language, it will look for that registered language file. For example, if you define lang="es", the grid will look for the es.js file.

If that file doesn't exist, then the grid will use smart defaults (algorithm defined below) for that language as best as it can for currency and date columns.

Algorithm

ZingGrid goes through several layers to detect the language/locale for the page. In this order, ZingGrid checks:

  1. The language set on the grid itself (e.g., <zing-grid lang="es">)
  2. The language set via registerLanguage with the default set to true (e.g., ZingGrid.registerLanguage(newLang, ‘en-US-x-twain’, true))
  3. The language set via setLanguage (e.g., ZingGrid.setLanguage(‘es’))
  4. The language set on the HTML tag (e.g., <html lang="de">)
  5. English

At each layer, we will start with the locale and break it down all the way to the language. If we ever get a match with built-in or a user added language file, we stop there.

For example, if lang is set to en-US-x-pirate:

  1. We will first look for a language match for en-US-x-pirate
  2. If there is no match, we will then look at en-US-x
  3. If there is no match, we will look at en-US
  4. If there is no match, we will look at en

Setting Language/ Locale

Columns with type currency, locale, and number will take a lang and locale attribute to properly display the given data. If these attributes are not provided, ZingGrid will look at the hierarchy specified above and find the most appropriate language and locale.

tag

You can set the language globally on the <html> tag with the lang attribute, like so:

<html lang="es">...</html>

tag

You can set the language per grid on the <zing-grid> tag with the lang attribute, like so:

<zing-grid lang="es"></zing-grid>

ZingGrid.setLanguage()

You can set the language globally with the API method setLanguage(), like so:

ZingGrid.setLanguage('es');

Custom Language

You can set a custom language by registering a language file with ZingGrid.registerLanguage(obj, 'custom') and the appropriate JavaScript object.

lang file

You will need to define a language file to create a custom mapping using our default export object (see below). You will typically name this language file the same as the language you are creating. For example, if lang="es", then you will create a file called es.js.

You can view the full default en.js language file online on our GitHub. We recommend using this as a reference to starting your own custom language.

export default {
  lang: 'en',
  columntypes: {
    editor: 'Edit',
    remover: 'Delete',
    selector: 'Select',
  },
  context: {
    copyCell: 'Copy Cell',
    pasteCell: 'Paste Cell',
    insertRecordLabel: 'Insert New Record',
    insertRecordHere: 'Here',
    insertRecordEnd: 'End',
    insertRecordStart: 'Start',
    deleteRow: 'Delete row',
    sortColumn: 'Sort Column',
    editCell: 'Edit Cell',
    editRow: 'Edit Row',
    selectCell: 'Select Cell',
    selectRow: 'Select Row',
    deselect: 'Deselect',
    previousPage: 'Go to previous page',
    nextPage: 'Go to next page',
    firstPage: 'Go to first page',
    lastPage: 'Go to last page',
    version: 'ZingGrid Version',
    save: 'Save',
    cancel: 'Cancel',
  },
  date: {
    shortMonth: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
    longMonth: ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'],
    twoWeek: ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa'],
    shortWeek: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
    longWeek: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
    am: 'am',
    pm: 'pm',
    startWeek: 0,
    startYear: 6,
  } ...
};

ZingGrid.registerLanguage()

Once you have defined a custom language file, you will use ZingGrid.registerLanguage(obj, 'custom') to actually register your custom language to the page (see below). There is typically a direct one-to-one mapping between your export lang key.

The second parameter of ZingGrid.registerLanguage can be used to register the language as a different name than your export.

let myLang = {
  lang: 'custom',
  context: {
    previousPage: 'custom-Go to previous page',
    nextPage: 'custom-Go to next page',
    firstPage: 'custom-Go to first page',
    lastPage: 'custom-Go to last page'
  } ...
};

ZingGrid.setLanguage(myLang, 'custom');

Custom Language Grid

Here is a complete grid with a custom language defined:

Column Types

Internationalization affects default column behavior. For example, if you define <zg-column type="date" locale="de">, it will add the appropriate date formatting to that column. The columns will default to the global <html lang=""> attribute, then <zing-grid lang="">, and then <zg-column lang=""> will override them all because it is the most specific.

The following column types have special language default formatting:

  1. <zg-column type="currency" type-currency="EUR">
  2. <zg-column type="date">
  3. <zg-column type="number">

If you want your data output in a different format, you can use a renderer or leave the column type as text and have it display exactly as the data is provided.

Currency

Your currency thousands separator will automatically format to the corresponding language default.

You still need the type-currency="EUR" attribute to define the currency symbol.

https://app.zingsoft.com/demos/embed/2PXNHT4S
https://app.zingsoft.com/demos/embed/2PXNHT4S

Number

Your number thousands separator will automatically format to the corresponding language default.

https://app.zingsoft.com/demos/embed/WWC173JM
https://app.zingsoft.com/demos/embed/WWC173JM

Date

Your date will automatically format to the corresponding language default. Add conventionally standard tokens (standard derived from moment.js) to date columns for custom date formatting, like so:

<zg-column type="date" type-date-format="[Month:] MM">

Date Tokens

Below is a comprehensive list of defined tokens in ZingGrid for date formatting with the attribute type-date-format.

Any tokens here that refer to a string (MMMM, dddd, etc.) must be set via a language file. It will take the strings from the language file being used for the specific column or the grid.
GroupingTokenOutput
MonthM1 2 ... 11 12
 Mo1st 2nd ... 11th 12th
 MM01 02 ... 11 12
 MMMJan Feb ... Nov Dec
 MMMMJanuary February ... November December
QuarterQ1 2 3 4
 Qo1st 2nd 3rd 4th
Day of MonthD1 2 ... 30 31
 Do1st 2nd ... 30th 31st
 DD01 02 ... 30 31
Day of YearDDD1 2 ... 364 365
 DDDo1st 2nd ... 364th 365th
 DDDD001 002 ... 364 365
Day of Weekd0 1 ... 5 6
 do0th 1st ... 5th 6th
 ddSu Mo ... Fr Sa
 dddSun Mon ... Fri Sat
 ddddSunday Monday ... Friday Saturday
Day of Week (Locale)e0 1 ... 5 6
Day of Week (ISO)E1 2 ... 6 7
Week of Yearw1 2 ... 52 53
 wo1st 2nd ... 52nd 53rd
 ww01 02 ... 52 53
Week of Year (ISO)W1 2 ... 52 53
 Wo1st 2nd ... 52nd 53rd
 WW01 02 ... 52 53
YearYY70 71 ... 29 30
 YYYY1970 1971 ... 2029 2030
 Y1970 1971 ... 9999 +10000 +10001 Note: This complies with the ISO 8601 standard for dates past the year 9999
Week Yeargg70 71 ... 29 30
 gggg1970 1971 ... 2029 2030
Week Year (ISO)GG70 71 ... 29 30
 GGGG1970 1971 ... 2029 2030
AM/PMAAM PM
 aam pm
HourH0 1 ... 22 23
 HH00 01 ... 22 23
 h1 2 ... 11 12
 hh01 02 ... 11 12
 k1 2 ... 23 24
 kk01 02 ... 23 24
Minutem0 1 ... 58 59
 mm00 01 ... 58 59
Seconds0 1 ... 58 59
 ss00 01 ... 58 59
Fractional SecondS0 1 ... 8 9
 SS00 01 ... 98 99
 SSS000 001 ... 998 999
 SSSS ... SSSSSSSSS000[0..] 001[0..] ... 998[0..] 999[0..]
Time ZoneZ-07:00 -06:00 ... +06:00 +07:00
 ZZ-0700 -0600 ... +0600 +0700
Unix TimestampX1360013296
Unix Millisecond Timestampx1360013296123

dir Attribute

The dir attribute sets the direction of grid's columns and text. ZingGrid supports the dir attribute inherited from the language or set directly on <zing-grid>.

dir Demo

Here is a demo that shows one grid with dir="ltr" (text direction left to right) and another with dir="rtl" (text direction right to left):

Sort

If the default language on the page is English, then we use standard sort. If you have any other language defined, you can override sort/filter functionality with the following properties:

  1. You can turn this off with <zing-grid sort-intl="disabled">
  2. <zing-grid sort-intl> and <zg-column sort-intl>

Filter/Search

ZingGrid will properly filter and search non-English characters when defining a language.