devextreme-intl

Integrates ECMAScript Internationalization API with DevExtreme

Usage no npm install needed!

<script type="module">
  import devextremeIntl from 'https://cdn.skypack.dev/devextreme-intl';
</script>

README

CircleCI

DevExtreme-Intl

IMPORTANT: This repo is in maintenance mode. Since v19.2, DevExtreme provides localization via Intl API out of the box, and this module is redundant. We do not recommend using it any longer.

This integration module enables localization of DevExtreme widgets using the global Intl object of the ECMAScript Internationalization API.

Using Intl is an alternative to the Globalize based mechanism documented here. Please note that in comparison to Globalize, there are some restrictions which are described in the section Restrictions below.

Getting started

Using a script tag

Add a script tag for devextreme-intl behind your tag for the devextreme script:

<script src="https://unpkg.com/devextreme-intl@18.2/dist/devextreme-intl.js"></script>

or

<script src="https://unpkg.com/devextreme-intl@18.2/dist/devextreme-intl.min.js"></script>

See this example with the relevant script tag in place.

Using npm modules

  1. Install the devextreme-intl module:

    npm install devextreme-intl

  2. Use an import call to make devextreme-intl available to your code:

    import 'devextreme-intl';

See this example using modules.

Browser support

Some older browsers don't support the ECMAScript Internationalization API. You can use the Intl.js polyfill to support a wide range of browsers.

API

In addition to the DevExtreme format object structure, formats can be specified which are compatible with the options parameter of the Intl NumberFormat and DateTimeFormat.

Note that the DevExtreme format object structure documentation page refers to special structures supported by Globalize. When using DevExtreme-Intl, these structures are either unsupported or need to adhere to Intl structural requirements instead.

Here is an example for the use of Intl formats in DataGrid columns:

$("#datagrid").dxDataGrid({
    dataSource: dataSource,
    columns: [{
        dataField: "OrderDate",
        format: { year: "2-digit", month: "narrow", day: "2-digit" }
    }, {
        dataField: "SaleAmount",
        format: { style: "currency", currency: "EUR", useGrouping: true, minimumSignificantDigits: 3 }
    }]
});

See more examples here.

You can find full documentation of the localization API in the DevExtreme documentation.

Restrictions

NOTE: Starting with version 17.2, these restrictions are not relevant.

Date parsing is not supported by the ECMAScript Internationalization API. You can read about the position of the ECMAScript community here. As a result, some minor DevExtreme functionality is restricted.

  • If you specify a displayFormat for the DateBox widget, any value typed into the editor by a user will not be parsed correctly.
  • If you enable searchPanel for the DataGrid widget, the search by date columns will not work.
  • If you configure a format for a DataGrid column, any value typed into the editor by a user will not be parsed correctly.

If a widget tries to parse a value in one of these scenarios, you will see this message in the JavaScript console:

W0012 - Date parsing is invoked while the parser is not defined. See: http://js.devexpress.com/error/W0012

You can specify a custom parser function as part of the displayFormat or column.format configuration objects to overcome this limitation. Here are some examples:

// Value will be parsed correctly
$("#datebox").dxDateBox({
    value: new Date()
});

// Value will not be parsed correctly
$("#datebox").dxDateBox({
    value: new Date(),
    displayFormat: {
        year: "numeric",
        month: "long"
    }
});

// Add a custom parser function
$("#datebox").dxDateBox({
    value: new Date(),
    displayFormat: {
        year: "numeric",
        month: "long",
        parser: function(dateString) {
            // return parsed date if possible
        }
    }
});

// Search and manual data entry will not work for the date column
$("#datagrid").dxDataGrid({
    dataSource: dataSource,
    searchPanel: {
        visible: true
    },
    columns: [{
        dataField: "OrderDate",
        format: {
            year: "numeric",
            month: "2-digit",
            day: "2-digit"
        }
    }]
});

// Add a custom parser function
$("#datagrid").dxDataGrid({
    dataSource: dataSource,
    searchPanel: {
        visible: true
    },
    columns: [{
        dataField: "OrderDate",
        format: {
            year: "numeric",
            month: "2-digit",
            day: "2-digit",
            parser: function(dateString) {
                // return parsed date if possible
            }
        }
    }]
});

Development

Install external development dependencies

npm install

Run tests

npm test

Build

Build the distribution UMD bundles devextreme-intl.js and devextreme-intl.min.js into the /dist folder.

npm run build

License

Familiarize yourself with the DevExtreme License.

DevExtreme integration with ECMAScript Internationalization API is released as an MIT-licensed (free and open-source) add-on to DevExtreme.

Support & Feedback