Localizing Telerik Report Viewers

 
HOW-TO
Localize the Telerik Reporting Win and Web Report Viewer controls' resources to a specific language or culture.

SOLUTION
In the Telerik Reporting Viewer controls localized resources are stored in separate RESX resource files and are loaded according to the current UI culture settings.

The default localization mechanism provided by the .NET Framework has some restrictions, which makes it hard for someone outside the Telerik team to localize the Report Viewer controls. The problem is that the Telerik Reporting assemblies are strongly named and signed with a private key. This requires all satellite localization assemblies to be signed with the same private key as well, which of course is not possible for someone outside Telerik.

To overcome this limitation the Report Viewer controls supports an alternative mechanism for localizing its resources. Instead of providing satellite resource assemblies, the Report Viewer controls can be localized directly from RESX resource files, as long as these RESX files conform to the required naming convention and are stored in the main application directory.

For complete description of the Report Viewer controls localization please see Report Viewer Localization.

Naming Conventions of the Localization Resources

Telerik Report Viewer controls use the following naming convention when searching for localized RESX resource files in the main application folder:

• For the Web Forms Report Viewer control, the names of the RESX localization resource files should have the following format:

Telerik.ReportViewer.WebForms.Resources.[culture].resx

• For the Windows Forms Report Viewer control, the names of the RESX localization resource files should have the following format:

Telerik.ReportViewer.WinForms.Resources.[culture].resx

Here [culture] is the name of the culture for the specified localization resource. For example, to provide a localization resource for the French Belgian culture, the corresponding resource file should be named as follows:

• For the Web Forms Report Viewer control:

Telerik.ReportViewer.WebForms.Resources.fr-BE.resx

• For the Windows Forms Report Viewer control:

Telerik.ReportViewer.WinForms.Resources.fr-BE.resx

Respectively, to provide a localization resource for the French neutral culture, the corresponding resource file should be named as follows:

• For the Web Forms Report Viewer control:

Telerik.ReportViewer.WebForms.Resources.fr.resx

• For the Windows Forms Report Viewer control:

Telerik.ReportViewer.WinForms.Resources.fr.resx

It is possible to override the default resources for the language neutral culture, which are stored in the assembly of the Report Viewer control. In that case the resource file should be named with no culture specified, as follows:

• For the Web Forms Report Viewer control:

Telerik.ReportViewer.WebForms.Resources.resx

• For the Windows Forms Report Viewer control:

Telerik.ReportViewer.WinForms.Resources.resx

As described above, if the current UI culture is set to French Belgian, for example, the Report Viewer control will search for localized RESX resource files inside the main application folder in the following order:

• For the Web Forms Report Viewer control:
  1. Telerik.ReportViewer.WebForms.Resources.fr-BE.resx
  2. Telerik.ReportViewer.WebForms.Resources.fr.resx
  3. Telerik.ReportViewer.WebForms.Resources.resx
      
• For the Windows Forms Report Viewer control:
  1. Telerik.ReportViewer.WinForms.Resources.fr-BE.resx
  2. Telerik.ReportViewer.WinForms.Resources.fr.resx
  3. Telerik.ReportViewer.WinForms.Resources.resx

 
Figure 1. The above diagram illustrates a simple view of resource fallback for a UI culture set to “fr-BE”. The Report Viewer handles this case probing the “fr-BE” RESX resource file for the requested key first, and subsequently falls back to the neutral culture “fr”, ultimately looking in the default assembly resources for a value if still not found.

Adding Localization Resources for the Report Viewer controls

• For the Web Forms Report Viewer:
  1. Add an ASP.NET folder “App_GlobalResources” to the main project of your web application or web site, if such folder does not exist.
  2. Add a new RESX resource file to the “App_GlobalResources” folder. Name the newly-created RESX file according to the naming convention described above.
  3. Open the RESX resource file in the Visual Studio Resource Editor. Enter the required resource strings to translate the Report Viewer to the desired language.
  4. To simplify the translation process, you can use the sample Report Viewer localization resources, that are attached to the current article. Open the attached resource file in the Visual Studio Resource Editor, select all of the resource strings, then copy and paste them to your existing localization resource file and translate them accordingly.
  5. Repeat the steps from 2 to 4 for each desired translation of the Report Viewer.
  6. Compile and run the project. When viewing a Telerik Report, the Report Viewer should be translated according to the current UI culture.
      
• For the Windows Forms Report Viewer:
  1. Add a new RESX resource file to the main project of your application. Name the newly-created RESX file according to the naming convention described above.
  2. In the Property Inspector specify the following properties for the resource file:
     • Build Action: “None”
     • Copy to Output Directory: “Copy if newer” or “Copy always”
  3. Open the RESX resource file in the Visual Studio Resource Editor. Enter the required resource strings to translate the Report Viewer to the desired language.
  4. To simplify the translation process, you can use the sample Report Viewer localization resources, that are attached to the current article. Open the attached resource file in the Visual Studio Resource Editor, select all of the resource strings, then copy and paste them to your existing localization resource file and translate them accordingly.
  5. Repeat the steps from 1 to 4 for each desired translation of the Report Viewer.
  6. Compile and run the project. When viewing a Telerik Report, the Report Viewer should be translated according to the current UI culture.

Distributing an Application with a Localized Report Viewer

In order to distribute an application that uses Telerik Reporting with a localized Report Viewer, one should distribute all of the required localization RESX resource files, in addition to the main application assemblies. For Web Sites and Web Applications the localization RESX resource files should be placed in the “App_GlobalResources” folder. For Windows Forms Applications the RESX files should be put in the same directory, where the application is installed.

SEE ALSO

• Hierarchical Organization of Resources for Localization
• Setting the Culture and UI Culture for Windows Forms Globalization
• Setting the Culture and UI Culture for Web Forms Globalization
• Security and Localized Satellite Assemblies