Localization in Reporting for Angular

• Jan 15, 2024
• 5 minutes to read

This topic describes how to localize the Document Viewer and End-User Report Designer UI in an Angular application.

Use JSON Files

In the Angular application you can import the localized JSON resources and use the CustomizeLocalization callback to call the LoadMessages method that loads localized strings.

Obtain JSON Files from the Localization Service

1. Log into the DevExpress website.

2. Open the DevExpress Localization Service.

3. Select your target language, modify translations, and click the Download button. Refer to the following help topic for detailed information: Localization Service.

4. 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

Tip

The component’s UI is built on DevExtreme widgets, so to localize the editors you should also use one of the approaches described in the following topic: DevExtreme - Localization. Specify web server’s thread culture to apply culture-specific formats to numbers and dates.

View Example: How to Localize the Reporting Controls in an Angular JavaScript Application

Localize the Application

The steps below are based on an Angular Reporting application created from DevExpress template as described in the following help topics:

• Use Visual Studio Templates to Create an Angular Application with a Document Viewer
• Use Visual Studio Templates to Create an Angular Application with a Report Designer

1. Copy the dx-analytics-core.xx.json and dx-reporting.xx.json (where xx is the culture ID) files obtained in the previous section to the application root folder (in this example, ClientApp\src).

2. Open a View file and insert the code that handles the CustomizeLocalization callback:

   report-viewer.html

   <dx-report-viewer [reportUrl]="reportUrl" height="800px">
       <dxrv-request-options [invokeAction]="invokeAction" [host]="hostUrl">
       </dxrv-request-options>
       <dxrv-callbacks (CustomizeLocalization)="CustomizeLocalization($event)">
       </dxrv-callbacks>
   </dx-report-viewer>
   

   report-designer.html

   <dx-report-designer [reportUrl]="reportUrl" height="700px">
       <dxrd-request-options [getDesignerModelAction]="getDesignerModelAction" [host]="hostUrl">
       </dxrd-request-options>
       <dxrd-callbacks (CustomizeLocalization)="CustomizeLocalization($event)">
       </dxrd-callbacks>
   </dx-report-designer>
   

3. Add the Angular compiler options to import local JSON modules. Open the tsconfig.json file and set the resolveJsonModule and esModuleInterop options to true:

   "compilerOptions": {
           "resolveJsonModule": true,
           "esModuleInterop": true,
       }
   

4. Open a View Model file and add the CustomizeLocalization event handler. Add import directives and use the LoadMessages method to load localized strings.

   report-viewer.ts

   // ...
   import localAnalyticMessages from "../../dx-analytics-core.xx.json";
   import localReportingMessages from "../../dx-reporting.xx.json";
   // ...
   export class ReportViewerComponent {
   reportUrl: string = "TestReport";
       invokeAction: string = '/DXXRDV';
       CustomizeLocalization(event) {
           event.args.LoadMessages(localAnalyticMessages);
           event.args.LoadMessages(localReportingMessages);
       }
   

   report-designer.ts

   // ...
   import localAnalyticMessages from "../../dx-analytics-core.xx.json";
   import localReportingMessages from "../../dx-reporting.xx.json";
   // ...
   export class ReportDesignerComponent {
       // If you use the ASP.NET Core backend:
       // getDesignerModelAction = "/DXXRD/GetDesignerModel"
       // If you use the ASP.NET MVC backend:
       getDesignerModelAction = "/ReportDesigner/GetReportDesignerModel";
       reportUrl = "TestReport";
       CustomizeLocalization(event) {
           event.args.LoadMessages(localAnalyticMessages);
           event.args.LoadMessages(localReportingMessages);
       }
   

5. Recompile the project and open the application in the browser (default URL is http://localhost:4200/).

Use UI Localization Client

Note

The UI Localization Client requires localization recourses to be loaded from the server to work properly in an Angular application.

The UI Localization Client is a cross-platform utility that allows you to quickly identify non-translated strings of DevExpress UI controls and translate them during a debug session. The utility automatically generates a RESX file(s) with translated resources and adds it to the project. Note that the UI Localization Client loads all Web Reporting resource strings once the controls are rendered, without reflecting your interaction with the UI.

To use the UI Localization Client in you application:

• Make sure that the application gets the localization from the server. For instance, you can use getLocalizationAction for Designer or getLocalizationAction for Viewer.
• Make sure you do not use the CustomizeLocalization event to localize your application.

For more information refer to the following topic: UI Localization Client.

The resource strings for the Web Reporting Controls (Web Document Viewer and Web Report Designer) are located in the following localization containers in the UI Localization Client window:

DevExpress.XtraReports.Web.Localization.LocalizationContainer

Contains localization strings specific only to the Web Reporting Controls.

DevExpress.Utils.Localization.CoreLibraryResources

Contains cross-platform localization strings used in the Web Reporting Controls.

DevExpress.Web.Resources.Localization.LocalizationContainer

Contains localization strings common to DevExpress Web Components used in the Web Reporting Controls.

Troubleshooting

• If you followed the instructions in the UI Localization Client topic and the translated resources do not appear on your web page, try clearing browser cache.
• If you use an ASP.NET Core backend and after following the instructions in the UI Localization Client topic the resource strings do not appear in the UI Localization Client window, call the HandleRequestsFromAllThreads() method at application startup to use localizer objects across all application threads.

Identify Non-Translated Strings

• Use our UI Localization Client tool shipped as part of your DevExpress subscription. This tool streamlines the entire localization process. You can quickly find non-translated strings and translate them during a debug session.
• Handle the XtraLocalizer.QueryLocalizedStringNonTranslated event to collect non-localized resource strings for further translation. The event allows you to focus on strings that require translation in your application.