Docs

Internationalization

ZingGrid has smart defaults for rendering zg-column(s) with type number, date, and currency through internationalization. A side effect from this implementation is smart filtering, sorting searching and dir.

Detecing lang/locale

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

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

algorithm

We go through several layers to detect the language/locale for the page. At each layer, we will start with the locale and break it down all the way to the lang. If we ever get a match with built in or user added language file, we stop there.

If the lang is set to en-US-x-pirate:

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

If there is still no match, we will go to the next layer of language detection. We go through the above process in this order until we find a supported language:

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

Setting lang/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.

html tag

You can set the language globally on the html tag with the lang attribute.

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

zing-grid tag

You can set the language per grid on the zing-grid tag with the lang attribute.

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

ZingGrid.setLanguage()

You can set the language globally with the API method setLanguage().

ZingGrid.setLanguage('es');

Custom Language

You can set a custom language by registering a lang 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. You will typically name this language file the same as the language you are creating. 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 referencing 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 the ZingGrid.registerLanguage(obj, 'custom') to actually register your custom language to the page. There is a 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');

Column Types

Internationalization affects default column behavior. If you defined <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

Will automatically format your currency thousands separator to the corresponding language default.

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

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

Number

Will automatically format your number thousands separator to the corresponding language default.

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

Date

Will automatically format your date formatting to the corresponding language default. Added conventionally standard tokens (standard derived from moment.js) to date columns for custom date formatting <zg-column type="date" type-date-format="[Month:] MM">

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

Date Tokens

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

ZingGrid supports the dir attribute inherited or set directly on <zing-grid dir="rtl">

Sort

If the default lang 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.