Report Viewer Localization

In the Windows Report Viewer, localized resources are stored in separate RESX resource files and loaded according to the current UI culture settings. To understand how localized resources are loaded, it is useful to think of them as being organized in a hierarchical manner.

Types of Resources in the Hierarchy

• At the top of the hierarchy sit the fallback resources for the default UI culture, which is English ("en") by default. These are the only resources that do not have their own file. They are stored directly in the assembly of the Report Viewer.
• Below the fallback resources are the resources for any neutral cultures. A neutral culture is associated with a language but not a region. For example, French ("fr") is a neutral culture. Note that the fallback resources are also for a neutral culture, but a special one.
• Below those are the resources for any specific cultures. A specific culture is associated with a language and a region. For example, French Canadian ("fr-CA") is a specific culture.

When the Report Viewer tries to load any localized resource and does not find it it will travel up the hierarchy until it finds a resource file containing the requested resource.

The best way to store your resources is to generalize them as much as possible. That means to store localized strings in resource files for neutral cultures rather than specific cultures whenever possible. For instance, if you have resources for the French Belgian ("fr-BE") culture and the resources immediately above are the fallback resources in English, a problem may result when someone uses your application on a system configured for the French Canadian culture. The Report Viewer will look for a RESX  file named "fr-CA", it will not find it and will load the fallback resource, which is English, instead of loading the French resources. The following picture shows this undesirable scenario.

If you follow the recommended practice of placing as many resources as possible in a neutral resource file for the "fr" culture, the French Canadian user would not see resources marked for the "fr-BE" culture, but he or she would still see strings in French. The following situation demonstrates this preferred scenario.

Naming Conventions for the Localization Resources

The Report Viewer uses the following naming convention when searching for localized RESX resource files in the main application folder:

• The names of the RESX localization resource files should have the following format: Telerik.ReportViewer.WinForms.Resources.[culture].resx, where [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: 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: 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. In that case the resource file should be named as follows: Telerik.ReportViewer.WinForms.Resources.resx

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

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

3. Telerik.ReportViewer.WinForms.Resources.resx

   

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

Adding Localization Resources for the Report Viewer

1. Add a new RESX resource file to the main project of the 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:

   1. Build Action: "None "
   2. 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. Repeat steps from 1 to 3 for each desired translation of the Report Viewer.
5. 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 Windows Forms Applications the RESX files should be placed in the same directory, where the application is installed.

See Also

• Windows Forms Application
• How to Add report viewer to a Windows Forms'.NET Framework project
• Setting the Culture for Windows Forms Globalization
• Setting the UI Culture for Windows Forms Globalization
• Localized Satellite Assemblies