Localize ASP.NET Core Reporting Components

• Mar 06, 2024
• 5 minutes to read

You can create localizable reports. Users can select a language to translate report content in the viewer, on the printed page, and in exported files. See the Localize Reports section for information on how to do this.

Additionally, you can localize the user interface in the Document Viewer and End-User Report Designer. See the Localize the User Interface section for information on how to do this.

Localize the User Interface

This section describes how to use JSON files from the DevExpress Localization Service to localize the Document Viewer and End-User Report Designer in ASP.NET Core applications.

Use JSON Files

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

Localize DevExtreme Widgets

Localize dates, numbers, currencies, and Devextreme widgets that are part of the Reporting component, as described in the following help topic: DevExtreme jQuery - Localization.

Load JSON Files in a Razor-Based Application

Do the following if you have a .NET Razor-based ASP.NET Core application and use the ReportDesigner or WebDocumentViewer extension method:

1. Copy the dx-analytics-core.xx.json and dx-reporting.xx.json files (where xx is the language identifier) to the application directory (for instance, wwwroot).

2. Open the View file and disable the IncludeLocalization setting to prevent the default localization strings from being loaded.

3. Handle the client-side ReportDesignerClientSideEventsBuilder.CustomizeLocalization (or WebDocumentViewerClientSideEventsBuilder.CustomizeLocalization) event.

4. In the event handler, use the argument’s LoadMessages method to load JSON files to a reporting component.

CSHTML

<script type="text/javascript" id="script">
    function CustomizeLocalization(s, e) {
        e.LoadMessages($.get('@Url.Content("/dx-analytics-core.xx.json")'));
        e.LoadMessages($.get('@Url.Content("/dx-reporting.xx.json")'));
    } 
</script>

@(Html.DevExpress().ReportDesigner("reportDesigner")
    .ClientSideModelSettings(x => x.IncludeLocalization = false)
    .ClientSideEvents(x => x.CustomizeLocalization("CustomizeLocalization"))
    .Height("1000px")
    .Bind("Report")) 

Use Localized Resources

You can obtain DevExpress localized resources as described in the Localization Service help topic, and use the ASP.NET Core framework standard localization technique. For more information, review the following Microsoft topic: Implement a strategy to select the language/culture for each request in a localized ASP.NET Core app.

Use UI Localization Client

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.

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 followed the instructions in the UI Localization Client topic and 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.

Localize Reports

The Report Designer enables you to localize a report for different target languages and cultures and store localized values in the REPX file.

Run Demo: Localization Feature Tour

Use Properties Panel

Perform the following actions to localize a report:

1. Specify a report language other than the Default:

   

   The Language drop-down list contains all available .NET locales. The report’s languages are highlighted in bold.

2. Change the controls’ property values. You can move and resize a control.

   

   Important

   When the report’s language is set to any language other than the Default language (localization mode), the Properties window shows only localizable properties. The localization mode does not allow you to add a new control from the Toolbar or use the Report Wizard.

3. Save the report.

When you load a localized report, use the Language drop-down list to enable localization mode and switch to the localized version.

Use Localization Editor

The Localization Editor allows you to change text strings in the report and expedite the translation process.

You can also implement the ITranslationService interface to automatically translate all text strings displayed within the Localization Editor to the selected language.

Note

Review the following article for more information: Localize Reports