DevExtreme jQuery/JS - Localization
Localization adapts your application to linguistic and regional differences. DevExtreme allows you to localize:
- Messages (using dictionaries)
- Numbers, dates, and currencies (using Intl or Globalize).
DevExtreme also supports right-to-left layout.
Dictionaries
Dictionaries contain localized strings for different languages. The strings are represented by key/value pairs and are shipped as JavaScript or JSON files (depending on the package you use).
DevExpress curates the following dictionaries:
- English (en) (default)
- German (de)
- Japanese (ja)
- Russian (ru)
There are also dictionaries that the community contributes and curates. The list of dictionaries is available on GitHub.
You can find all the dictionaries on your local machine in the DevExtreme installation folder's or ZIP archive's Lib\js\localization directory. These dictionaries are also available on CDN or npm.
CDN or local file
Link the required dictionaries using the
<script>
tag.CDN
HTML<head> <!-- ... --> <!-- DevExtreme library --> <script src="https://cdn3.devexpress.com/jslib/19.1.16/js/dx.all.js"></script> <!-- Dictionary files for German and Russian languages --> <script src="https://cdn3.devexpress.com/jslib/19.1.16/js/localization/dx.messages.de.js"></script> <script src="https://cdn3.devexpress.com/jslib/19.1.16/js/localization/dx.messages.ru.js"></script> </head> <body> <script> DevExpress.localization.locale(navigator.language); // ... // DevExtreme widgets are configured here // ... </script> </body>
npm
Include the dictionaries using the
import
orrequire
statement—the statement depends on the syntax for working with modules. The following code shows ECMAScript 6 and CommonJS syntaxes:npm: ECMAScript 6 syntax
JavaScript// ... // Dictionaries for German and Russian languages import deMessages from "devextreme/localization/messages/de.json"; import ruMessages from "devextreme/localization/messages/ru.json"; // In projects created with Angular CLI earlier than 6 // import deMessages from "devextreme/localization/messages/de.json!json"; // import ruMessages from "devextreme/localization/messages/ru.json!json"; import { locale, loadMessages } from "devextreme/localization"; // ===== Angular ====== export class AppComponent { constructor() { loadMessages(deMessages); loadMessages(ruMessages); locale(navigator.language); } } // ===== Vue ====== export default { created() { loadMessages(deMessages); loadMessages(ruMessages); locale(navigator.language); } } // ===== React ====== class App extends React.Component { constructor(props) { super(props); loadMessages(deMessages); loadMessages(ruMessages); locale(navigator.language); } }
npm: CommonJS syntax
JavaScript// ... // Dictionaries for German and Russian languages const deMessages = require('devextreme/localization/messages/de.json'); const ruMessages = require('devextreme/localization/messages/ru.json'); const localization = require('devextreme/localization'); localization.loadMessages(deMessages); localization.loadMessages(ruMessages); localization.locale(navigator.language);
Create a New Dictionary
To make a dictionary for a new locale:
- Copy one of the available dictionaries.
- Rename it according to the new locale.
- Translate the strings in it and change the locale key.
You can submit JSON dictionaries to our repository on GitHub. You should refer to our Contribution Guide before submitting content.
Add Strings to a Dictionary
In the following example, the loadMessages(messages) method adds a string with the greetingMessage
key to the English and German dictionaries. The formatMessage(key, value) method then uses this key to retrieve the string from the dictionary that corresponds to the locale set by the locale(locale) method.
jQuery
$(function() { var userName = "John"; DevExpress.localization.loadMessages({ "en": { "greetingMessage": "Good morning, {0}!" }, "de": { "greetingMessage": "Guten morgen, {0}!" } }); DevExpress.localization.locale(navigator.language); $("#greeting").text( DevExpress.localization.formatMessage("greetingMessage", userName); ) })
<h1 id="greeting"></h1>
Angular
import { Component } from '@angular/core'; import { formatMessage, loadMessages, locale } from 'devextreme/localization'; @Component({ selector: 'app-root', templateUrl: './app.component.html', styleUrls: ['./app.component.css'] }) export class AppComponent { constructor() { loadMessages({ 'en': { 'greetingMessage': 'Good morning, {0}!' }, 'de': { 'greetingMessage': 'Guten morgen, {0}!' } }); locale(navigator.language); } userName: string = 'John'; get greeting() { return formatMessage('greetingMessage', this.userName); } }
<h1>{{ greeting }}</h1>
Vue
<template> <h1>{{ greeting }}</h1> </template> <script> import { formatMessage, loadMessages, locale } from 'devextreme/localization'; export default { created() { loadMessages({ 'en': { 'greetingMessage': 'Good morning, {0}!' }, 'de': { 'greetingMessage': 'Guten morgen, {0}!' } }); locale('de'); }, data() { return { userName: 'John' } }, computed: { greeting() { return formatMessage('greetingMessage', this.userName); } } } </script>
React
import React from 'react'; import { formatMessage, loadMessages, locale } from 'devextreme/localization'; class App extends React.Component { constructor(props) { super(props); this.userName = 'John'; loadMessages({ 'en': { 'greetingMessage': 'Good morning, {0}!' }, 'de': { 'greetingMessage': 'Guten morgen, {0}!' } }); this.greeting = formatMessage('greetingMessage', this.userName); locale(navigator.language); } render() { return ( <h1>{ this.greeting }</h1> ); } } export default App;
Override Strings in a Dictionary
To override a string, find its key in any dictionary and use it to specify the new string value.
In the following code, we override two strings from the English dictionary:
jQuery
$(function() { DevExpress.localization.loadMessages({ "en": { "dxDataGrid-editingDeleteRow": "Remove", "dxDataGrid-editingUndeleteRow": "Recover" } }); });
Angular
import { Component } from '@angular/core'; import { loadMessages } from 'devextreme/localization'; @Component({ selector: 'app-root', templateUrl: './app.component.html', styleUrls: ['./app.component.css'] }) export class AppComponent { constructor() { loadMessages({ "en": { "dxDataGrid-editingDeleteRow": "Remove", "dxDataGrid-editingUndeleteRow": "Recover" } }); } }
Vue
<template> <!-- ... --> </template> <script> import { loadMessages } from 'devextreme/localization'; export default { created() { loadMessages({ "en": { "dxDataGrid-editingDeleteRow": "Remove", "dxDataGrid-editingUndeleteRow": "Recover" } }); } } </script>
React
import React from 'react'; import { loadMessages } from 'devextreme/localization'; class App extends React.Component { constructor(props) { super(props); loadMessages({ "en": { "dxDataGrid-editingDeleteRow": "Remove", "dxDataGrid-editingUndeleteRow": "Recover" } }); } render() { return ( { /* ... */} ); } } export default App;
Using Intl
Intl is the short name used to refer to a particular ECMAScript Internationalization API object. DevExtreme supports this API via the DevExtreme-Intl module. It is available on CDN and npm, or you can save the module (JavaScript file) on your local machine.
CDN or local file
Use the
<script>
tag as shown in the example below to include the DevExtreme-Intl module. German and Russian dictionaries are included in this example. You can also add or replace dictionaries.CDN
HTML<head> <!-- ... --> <!-- DevExtreme library --> <script src="https://cdn3.devexpress.com/jslib/19.1.16/js/dx.all.js"></script> <!-- DevExtreme-Intl module --> <script src="https://unpkg.com/devextreme-intl@19.1/dist/devextreme-intl.min.js"></script> <!-- Dictionary files for German and Russian languages --> <script src="https://cdn3.devexpress.com/jslib/19.1.16/js/localization/dx.messages.de.js"></script> <script src="https://cdn3.devexpress.com/jslib/19.1.16/js/localization/dx.messages.ru.js"></script> </head> <body> <script> DevExpress.localization.locale(navigator.language); // ... // DevExtreme widgets are configured here // ... </script> </body>
npm
Install the
devextreme-intl
package:npm install --save-dev devextreme-intl
Then, include the
devextreme-intl
module using theimport
orrequire
statement—the statement depends on the syntax for working with modules. The code below shows ECMAScript 6 and CommonJS syntaxes. These examples include German and Russian dictionaries.npm: ECMAScript 6 syntax
JavaScript// ... import "devextreme-intl"; // Dictionaries for German and Russian languages import deMessages from "devextreme/localization/messages/de.json"; import ruMessages from "devextreme/localization/messages/ru.json"; // In projects created with Angular CLI earlier than 6 // import deMessages from "devextreme/localization/messages/de.json!json"; // import ruMessages from "devextreme/localization/messages/ru.json!json"; import { locale, loadMessages } from "devextreme/localization"; // ===== Angular ====== export class AppComponent { constructor() { loadMessages(deMessages); loadMessages(ruMessages); locale(navigator.language); } } // ===== Vue ====== export default { created() { loadMessages(deMessages); loadMessages(ruMessages); locale(navigator.language); } } // ===== React ====== class App extends React.Component { constructor(props) { super(props); loadMessages(deMessages); loadMessages(ruMessages); locale(navigator.language); } }
npm: CommonJS syntax
JavaScript// ... require("devextreme-intl"); // Dictionaries for German and Russian languages const deMessages = require('devextreme/localization/messages/de.json'); const ruMessages = require('devextreme/localization/messages/ru.json'); const localization = require('devextreme/localization'); localization.loadMessages(deMessages); localization.loadMessages(ruMessages); localization.locale(navigator.language);
Strings, numbers, dates, and currencies are now automatically localized and formatted according to the specified locale. You can also specify a currency other than USD globally (using the defaultCurrency setting) or in format definitions:
jQuery
$(function() { // Specifying a currency globally DevExpress.config({ defaultCurrency: "EUR" }); $("#dataGridContainer").dxDataGrid({ // ... columns: [{ dataField: "Price", // Specifying a currency in a format definition format: { type: "currency", currency: "RUB" } }] }); });
Angular
import { Component } from '@angular/core'; import config from 'devextreme/core/config'; // ... // import dictionaries and localization modules here @Component({ selector: 'app-root', templateUrl: './app.component.html', styleUrls: ['./app.component.css'] }) export class AppComponent { constructor() { // Specifying a currency globally config({ defaultCurrency: 'EUR' }); } }
<dx-data-grid ... > <dxi-column dataField="price"> <!-- Specifying a currency in a format definition --> <dxo-format type="currency" currency="RUB"> </dxo-format> </dxi-column> </dx-data-grid>
import { BrowserModule } from '@angular/platform-browser'; import { NgModule } from '@angular/core'; import { AppComponent } from './app.component'; import { DxDataGridModule } from 'devextreme-angular'; @NgModule({ declarations: [ AppComponent ], imports: [ BrowserModule, DxDataGridModule ], providers: [ ], bootstrap: [AppComponent] }) export class AppModule { }
Vue
<template> <DxDataGrid ... > <DxColumn data-field="price"> <!-- Specifying a currency in a format definition --> <DxFormat type="currency" currency="RUB" /> </DxColumn> </DxDataGrid> </template> <script> import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; // ... // import dictionaries and localization modules here import config from 'devextreme/core/config'; import DxDataGrid, { DxColumn, DxFormat } from 'devextreme-vue/data-grid'; export default { components: { DxDataGrid, DxColumn, DxFormat }, created() { // Specifying a currency globally config({ defaultCurrency: 'EUR' }); } } </script>
React
import React from 'react'; import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; import DataGrid, { Column, Format } from 'devextreme-react/data-grid'; // ... // import dictionaries and localization modules here class App extends React.Component { constructor(props) { super(props); // Specifying a currency globally config({ defaultCurrency: 'EUR' }); } render() { return ( <DataGrid ... > <Column dataField="price"> // Specifying a currency in a format definition <Format type="currency" currency="RUB" /> </Column> </DataGrid> ); } } export default App;
You can use structures compatible with the Intl API for value formatting. See an example in the DevExtreme-Intl README's API section. The Value Formatting article provides information on the extended formatting functionality DevExtreme provides out of the box.
You can use the Intl-Angular sample project as a starting point for creating new apps or as an example to copy code from when implementing specific functionality in your app.
Using Globalize
Activating Globalize in your project requires the following files:
- Globalize library
- CLDR library
- CLDR data
All the components are available via CDN and npm.
CDN or local files
Include the Globalize and CLDR libraries using
<script>
tags as shown below. In this example, German and Russian dictionaries are also included. Note that the order you include the libraries is important. Then, set the locale using theGlobalize.locale()
method:CDN
HTML<head> <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.5.1/jquery.min.js"></script> <!-- ... --> <script src="https://cdnjs.cloudflare.com/ajax/libs/cldrjs/0.5.0/cldr.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/cldrjs/0.5.0/cldr/event.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/cldrjs/0.5.0/cldr/supplemental.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/globalize/1.3.0/globalize.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/globalize/1.3.0/globalize/message.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/globalize/1.3.0/globalize/number.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/globalize/1.3.0/globalize/currency.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/globalize/1.3.0/globalize/date.min.js"></script> <!-- DevExtreme library --> <script src="https://cdn3.devexpress.com/jslib/19.1.16/js/dx.all.js"></script> <!-- Dictionary files for German and Russian languages --> <script src="https://cdn3.devexpress.com/jslib/19.1.16/js/localization/dx.messages.de.js"></script> <script src="https://cdn3.devexpress.com/jslib/19.1.16/js/localization/dx.messages.ru.js"></script> <!-- Common and language-specific CLDR data --> <script src="https://unpkg.com/devextreme-cldr-data/supplemental.js"></script> <script src="https://unpkg.com/devextreme-cldr-data/de.js"></script> <script src="https://unpkg.com/devextreme-cldr-data/ru.js"></script> </head> <script> $(function() { Globalize.locale(navigator.language); }); </script>
npm
Install the
devextreme-cldr-data
andglobalize
packages:npm install --save-dev devextreme-cldr-data globalize
Register Globalize in your project as described in the Angular, Vue, or React articles.
Then, include Globalize, CLDR, and language-specific CLDR data using the
import
orrequire
statement—the statement depends on the syntax for working with modules. The code below shows ECMAScript 6 and CommonJS syntaxes. These examples include German and Russian dictionaries.npm: ECMAScript 6 syntax
JavaScriptimport "devextreme/localization/globalize/number"; import "devextreme/localization/globalize/date"; import "devextreme/localization/globalize/currency"; import "devextreme/localization/globalize/message"; // Dictionaries for German and Russian languages import deMessages from "devextreme/localization/messages/de.json"; import ruMessages from "devextreme/localization/messages/ru.json"; // Common and language-specific CLDR JSONs import supplemental from "devextreme-cldr-data/supplemental.json"; import deCldrData from "devextreme-cldr-data/de.json"; import ruCldrData from "devextreme-cldr-data/ru.json"; // In projects created with Angular CLI earlier than 6 // import deMessages from "devextreme/localization/messages/de.json!json"; // import ruMessages from "devextreme/localization/messages/ru.json!json"; // import supplemental from "devextreme-cldr-data/supplemental.json!json"; // import deCldrData from "devextreme-cldr-data/de.json!json"; // import ruCldrData from "devextreme-cldr-data/ru.json!json"; import Globalize from "globalize"; // ===== Angular ====== export class AppComponent { constructor() { Globalize.load( supplemental, deCldrData, ruCldrData ); Globalize.loadMessages(deMessages); Globalize.loadMessages(ruMessages); Globalize.locale(navigator.language); } } // ===== Vue ====== export default { created() { Globalize.load( supplemental, deCldrData, ruCldrData ); Globalize.loadMessages(deMessages); Globalize.loadMessages(ruMessages); Globalize.locale(navigator.language); } } // ===== React ====== class App extends React.Component { constructor(props) { super(props); Globalize.load( supplemental, deCldrData, ruCldrData ); Globalize.loadMessages(deMessages); Globalize.loadMessages(ruMessages); Globalize.locale(navigator.language); } }
npm: CommonJS syntax
JavaScriptrequire('devextreme/localization/globalize/message'); require('devextreme/localization/globalize/number'); require('devextreme/localization/globalize/currency'); require('devextreme/localization/globalize/date'); // Dictionaries for German and Russian languages const deMessages = require('devextreme/localization/messages/de.json'); const ruMessages = require('devextreme/localization/messages/ru.json'); const Globalize = require('globalize'); Globalize.load( // Common and language-specific CLDR JSONs require('devextreme-cldr-data/supplemental.json'), require('devextreme-cldr-data/main/de.json'), require('devextreme-cldr-data/main/ru.json') ); Globalize.loadMessages(deMessages); Globalize.loadMessages(ruMessages); Globalize.locale(navigator.language);
Strings, numbers, dates, and currencies are now automatically localized and formatted according to the specified locale. You can also use a currency other than USD (see the last example in the Using Intl topic).
In addition, you can now format values using structures accepted by numberFormatter, currencyFormatter, and dateFormatter, for example:
jQuery
$(function() { $("#dataGridContainer").dxDataGrid({ // ... columns: [{ dataField: "OrderDate", format: { skeleton: "yMMMd" } }, { dataField: "SaleAmount", format: { currency: "EUR", maximumFractionDigits: 2 } }] }); });
Angular
<dx-data-grid ... > <dxi-column dataField="OrderDate" [format]="{ skeleton: 'yMMMd' }"> </dxi-column> <dxi-column dataField="SaleAmount" [format]="{ currency: 'EUR', maximumFractionDigits: 2 }"> </dxi-column> </dx-data-grid>
import { Component } from '@angular/core'; // ... // import dictionaries and localization modules here @Component({ selector: 'app-root', templateUrl: './app.component.html', styleUrls: ['./app.component.css'] }) export class AppComponent { // ... }
import { BrowserModule } from '@angular/platform-browser'; import { NgModule } from '@angular/core'; import { AppComponent } from './app.component'; import { DxDataGridModule } from 'devextreme-angular'; @NgModule({ declarations: [ AppComponent ], imports: [ BrowserModule, DxDataGridModule ], providers: [ ], bootstrap: [AppComponent] }) export class AppModule { }
Vue
<template> <DxDataGrid ... > <DxColumn data-field="OrderDate" :format="{ skeleton: 'yMMMd' }" /> <DxColumn data-field="SaleAmount" :format="{ currency: 'EUR', maximumFractionDigits: 2 }" /> </DxDataGrid> </template> <script> import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; // ... // import dictionaries and localization modules here import DxDataGrid, { DxColumn } from 'devextreme-vue/data-grid'; export default { components: { DxDataGrid, DxColumn }, // ... } </script>
React
import React from 'react'; import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; import DataGrid, { Column } from 'devextreme-react/data-grid'; // ... // import dictionaries and localization modules here class App extends React.Component { constructor(props) { super(props); // ... } render() { return ( <DataGrid ... > <Column dataField="price" format={{ currency: 'EUR', maximumFractionDigits: 2 }} /> </DataGrid> ); } } export default App;
See Also
Localize Custom Values
DevExtreme provides an API for localizing messages, dates, and numbers in your app.
To localize a message, add it to a dictionary as shown in the Add Strings to a Dictionary article.
To localize a custom date or number, apply a format to it as shown in the Format Custom Values article. You app should have Intl or Globalize configured.
Right-to-Left Support
Right-to-left (RTL) support allows the widget to adapt its content to right-to-left locales.
RTL layout can be specified for an individual widget using its rtlEnabled option:
jQuery
$(function() { $("#sliderContainer").dxSlider({ // ... rtlEnabled: true }); });
Angular
<dx-slider ... [rtlEnabled]="true"> </dx-slider>
import { Component } from '@angular/core'; @Component({ selector: 'app-root', templateUrl: './app.component.html', styleUrls: ['./app.component.css'] }) export class AppComponent { // ... }
import { BrowserModule } from '@angular/platform-browser'; import { NgModule } from '@angular/core'; import { AppComponent } from './app.component'; import { DxSliderModule } from 'devextreme-angular'; @NgModule({ declarations: [ AppComponent ], imports: [ BrowserModule, DxSliderModule ], providers: [], bootstrap: [AppComponent] }) export class AppModule { }
Vue
<template> <DxSlider ... :rtl-enabled="true" /> </template> <script> import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; import DxSlider from 'devextreme-vue/slider'; export default { components: { DxSlider } } </script>
React
import React from 'react'; import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; import Slider from 'devextreme-react/slider'; class App extends React.Component { render() { return ( <Slider ... rtlEnabled={true} /> ); } } export default App;
To apply RTL to your entire application, set the same option globally using the config() function:
jQuery
$(function() { DevExpress.config({ rtlEnabled: true }); // ... });
Angular
import { Component } from '@angular/core'; import config from 'devextreme/core/config'; @Component({ selector: 'app-root', templateUrl: './app.component.html', styleUrls: ['./app.component.css'] }) export class AppComponent { constructor() { config({ rtlEnabled: true }); } }
Vue
<template> <!-- ... --> </template> <script> import config from 'devextreme/core/config'; export default { // ... created() { config({ rtlEnabled: true }); } } </script>
React
import React from 'react'; import config from 'devextreme/core/config'; class App extends React.Component { constructor(props) { super(props); config({ rtlEnabled: true }); } render() { return ( // ... ); } } export default App;
See Also
- RTL Support Demo: DataGrid | Navigation Widgets | Editors