Localization
- 4 minutes to read
This document describes how to use JSON files from the DevExpress Localization Service to localize the Document Viewer and End-User Report Designer in JavaScript and JavaScript with Angular applications.
Obtain JSON Files from the Localization Service
Log into the DevExpress website.
Open the DevExpress Localization Service.
Select your target language, modify translations, and click the Download button. Refer to the Localization Service documentation topic for more information.
Unpack the downloaded executable file to get the satellite assemblies and json resources directory. This directory contains the following JSON files required to localize the reporting controls (where xx is a culture name):
File Name | Localization Strings |
---|---|
dx-analytics-core.xx.json | Shared Components: Query Builder, Data Source Wizard, Filter Editor, Expression Editor |
dx-reporting.xx.json | Web Document Viewer, End-User Report Designer and other reporting-specific components |
Localization in a Knockout-based Application (React, Vue and other JS Frameworks)
Note
The complete sample project How to Localize the Reporting Controls in a JavaScript Application with Knockout Bindings is available in the DevExpress Examples repository.
Use JSON Files from the Localization Service
Follow the steps below if you have a JavaScript application that uses Knockout bindings to integrate the End-User Web Report Designer or HTML5 Document Viewer components:
Copy the dx-analytics-core.xx.json and dx-reporting.xx.json files to the application directory (in this example. ClientSide).
Add the CustomizeLocalization callback to the designerOptions or vieweroptions variable. The callback defines a JavaScript function that loads the localization strings from JSON files with the argument’s LoadMessages method.
Client-side localization is the preferable approach. You can combine it with the custom localization approach described below.
const host = 'http://localhost:56742/',
reportUrl = "Products",
designerOptions = {
reportUrl: reportUrl,
requestOptions: {
host: host,
getDesignerModelAction: "/ReportDesigner/GetReportDesignerModel"
},
callbacks: {
// Handle the CustomizeLocalization event to load the DevExpress Localization Service JSON files.
CustomizeLocalization: function (s, e) {
e.LoadMessages($.get("/dx-analytics-core.de.json")); // Load files obtained from DevExpress Localization Service.
e.LoadMessages($.get("/dx-reporting.de.json")); // Load files obtained from DevExpress Localization Service.
}
}
};
ko.applyBindings({ designerOptions });
Localize Specific Strings
Call the ASPxClientReportDesigner.UpdateLocalization(localization) or the ASPxClientWebDocumentViewer.UpdateLocalization(localization) function to localize specific strings.
You can use only this approach or combine it with the basic localization approach.
const host = 'http://localhost:56742/',
reportUrl = "Products",
designerOptions = {
reportUrl: reportUrl,
requestOptions: {
host: host,
getDesignerModelAction: "/ReportDesigner/GetReportDesignerModel"
},
callbacks: {
// Handle the CustomizeLocalization event and call the UpdateLocalization method
// to localize a particular string.
CustomizeLocalization: function (s, e) {
s.UpdateLocalization({
'Properties': 'TEST',
'Data Source': 'Datenquelle',
'Data Member': 'Datenelement'
});
}
}
};
ko.applyBindings({ designerOptions });
Use Satellite Assemblies
Specify the getLocalizationAction setting that is the path to the controller action that retrieves the localized strings. You can combine this approach with the custom localization approach.
Note
The code below is for the End-User Web Report Designer. You can use the same approach described in previous steps for the HTML5 Document Viewer.
const host = 'http://localhost:56742/',
reportUrl = "Products",
designerOptions = {
reportUrl: reportUrl,
requestOptions: {
host: host,
getDesignerModelAction: "/ReportDesigner/GetReportDesignerModel", // Action that returns the Report Designer model.
// Use this action to get the localized strings from the server.
getLocalizationAction: "/ReportDesigner/GetLocalization"
}
};
ko.applyBindings({ designerOptions });
Localization in an Angular-Based Application
Note
The complete sample project How to Localize the Reporting Controls in an Angular JavaScript Application is available in the DevExpress Examples repository.
Note
The steps below are for the End-User Web Report Designer. However, the same approach works for the HTML5 Document Viewer.
Follow the steps below if you use the dx-report-viewer/dx-report-designer Angular component and a backend ASP.NET MVC application:
Copy the dx-analytics-core.xx.json and dx-reporting.xx.json files to the root application folder (in this example, JS\angular-report-designer\src).
Open a View file (in this example - JS\angular-report-designer\src\app\app.component.html) and overwrite its contents with the code below. The code handles the CustomizeLocalization callback.
<div> <dx-report-designer [reportUrl]="reportUrl" height="700px" [allowMDI]="allowMDI" cssClass='myDesigner'> <dxrd-request-options [getDesignerModelAction]="getDesignerModelAction" [host]="hostUrl"></dxrd-request-options> <dxrd-callbacks (CustomizeLocalization)="CustomizeLocalization($event)"> </dxrd-callbacks> </dx-report-designer> </div>
Open a View Model file (in this example - JS\angular-report-designer\src\app\app.component.ts) and add the CustomizeLocalization event handler. Use the LoadMessages method to load JSON files that contain localized strings. The app.component.ts should have the following content:
import { Component, ViewEncapsulation } from '@angular/core'; import 'devexpress-reporting/dx-richedit'; import deAnalyticMessages from "../dx-analytics-core.de.json"; import deReportingMessages from "../dx-reporting.de.json"; @Component({ selector: 'app-root', encapsulation: ViewEncapsulation.None, templateUrl: './app.component.html', styleUrls: [ "../../node_modules/jquery-ui/themes/base/all.css", "../../node_modules/devextreme/dist/css/dx.common.css", "../../node_modules/devextreme/dist/css/dx.light.css", "../../node_modules/devexpress-richedit/dist/dx.richedit.css", "../../node_modules/@devexpress/analytics-core/dist/css/dx-analytics.common.css", "../../node_modules/@devexpress/analytics-core/dist/css/dx-analytics.light.css", "../../node_modules/@devexpress/analytics-core/dist/css/dx-querybuilder.css", "../../node_modules/devexpress-reporting/dist/css/dx-webdocumentviewer.css", "../../node_modules/devexpress-reporting/dist/css/dx-reportdesigner.css" ] }) export class AppComponent { title = 'DXReportDesignerSample'; getDesignerModelAction = "/ReportDesigner/GetReportDesignerModel"; reportUrl = "Products"; hostUrl = 'http://localhost:56742/'; CustomizeLocalization(event) { event.args.LoadMessages(deAnalyticMessages); event.args.LoadMessages(deReportingMessages); } }
Add the Angular compiler options to import local JSON modules. Open the JS\angular-report-designer\tsconfig.json file and set the resolveJsonModule and esModuleInterop options to true:
{ "compileOnSave": false, "compilerOptions": { "resolveJsonModule":true, "esModuleInterop":true, ... } }
- Recompile the project (Angular CLI recompiles the project automatically) and open the application in the browser (default URL is http://localhost:4200/).