Skip to content

Latest commit

 

History

History
382 lines (291 loc) · 16.7 KB

common-localization.md

File metadata and controls

382 lines (291 loc) · 16.7 KB
Raw
title page_title description slug tags published position
Localization
Localization
Localization
common-localization
localization
true
17

Localization

When you limit your product's availability to only one language, you limit your potential customer base to a fraction of the world population. If you want your application to reach a global audience, cost-effective localization of your product is one of the best and most economical ways to reach more customers.

Localization is the translation of application resources into localized versions for the specific cultures that the application supports.

This article will show you how to localize any resource string used by Telerik UI controls. We will discuss the following topics:

All examples in this article are demonstrated in the context of the Telerik RadGridView control. However, the techniques and principles used for the localization of the string resources are valid for all the other Telerik {% if site.site_name == 'WPF' %}WPF{% endif %}{% if site.site_name == 'Silverlight' %}Silverlight{% endif %} controls.

Localization Using Built-in Resources

The built-in localization mechanism in {% if site.site_name == 'WPF' %}WPF{% endif %}{% if site.site_name == 'Silverlight' %}Silverlight{% endif %} provides the possibility to easily set the used Telerik {% if site.site_name == 'WPF' %}WPF{% endif %}{% if site.site_name == 'Silverlight' %}Silverlight{% endif %} controls in one of the following supported languages:

  • English

  • German

  • Spanish

  • French

  • Italian

  • Dutch

  • Turkish

The default is English, but you can find a separate file for each of the other languages in a corresponding folder together with the other binaries in your local installation.

If you need to translate your control into a different language, you should use a Custom Localization Manager.

To localize your controls using the built-in localization mechanism, you first have to place the resource folders along with the binaries you have referenced as shown in Figure 3.

Figure 1: Placing the resource folders in your project

Common Localization 050

{% if site.site_name == 'Silverlight' %} Then, you must define your preferred languages in the tag of your project file in order to notify the framework about the supported cultures. To do so, open the project file with a text editor and insert the code below into the <PropertyGroup> section.

[XAML] Example 1: Setting supported cultures

{{region common-localization_4}} en;nl {{endregion}}

The next step for defining the language settings of the application is changing the Current Culture of the application.

[C#] Example 2: Setting the current culture of the application

{{region common-localization_11}} private void Application_Startup(object sender, StartupEventArgs e) { Thread.CurrentThread.CurrentCulture = new CultureInfo("de"); Thread.CurrentThread.CurrentUICulture = new CultureInfo("de");

    this.RootVisual = new MainPage();
}

{{endregion}}

[VB.NET] Example 2: Setting the current culture of the application

{{region common-localization_12}} Private Sub Application_Startup(sender As Object, e As StartupEventArgs) Thread.CurrentThread.CurrentCulture = New CultureInfo("de") Thread.CurrentThread.CurrentUICulture = New CultureInfo("de")

    Me.RootVisual = New MainPage()
End Sub

{{endregion}}

{% endif %}

{% if site.site_name == 'WPF' %} The next step for defining the language settings of the application is changing the Current Culture of the application:

[C#] Example 1: Setting the current culture of the application

{{region common-localization_9}} public App() { Thread.CurrentThread.CurrentCulture = new CultureInfo("de"); Thread.CurrentThread.CurrentUICulture = new CultureInfo("de"); } {{endregion}}

[VB.NET] Example 1: Setting the current culture of the application

{{region common-localization_10}} Public Sub New() Thread.CurrentThread.CurrentCulture = New CultureInfo("de") Thread.CurrentThread.CurrentUICulture = New CultureInfo("de") End Sub {{endregion}}

{% endif %}

That's it. Your controls should now be localized in the preferred language.

Figure 2: RadGridView localized in German

Common_Localization_070

Resource Keys

Some of the controls are complex user interface controls (e.g., RadGridView, RadScheduleView) and their strings for localization are numerous. In order to be able to distinguish these resources, a unique identifier called resource key is assigned to each localizable string.

In Figure 3 you can see some resource keys and the strings they are associated with.

Figure 3: Some of RadGridView's resource keys and their values

Common_Localization_060

tipFor a full list of resource keys, check out the Localization topic for the specific control.

Localization Using ResourceManager

If you need to modify the default strings for a chosen language, you can base your localization on the standard resource files. For that purpose, you will have to create a separate .resx file for each of the languages that your application will support.

Imagine that you want to translate your control, RadGridView for example, into English, German and Dutch. You will have to add three new resource files to your project:

  • GridViewResources.resx - this resource file will store the English(default) resources for the grid control. Set the AccessModifier property to Public.

  • GridViewResources.de.resx - this resource file will store the German resources for the grid control. Set the AccessModifier property to No code generation.

  • GridViewResources.nl.resx - this resource file will store the Dutch resources for the grid control. Set the AccessModifier property to No code generation.

Figure 4: Creating separate .resx files for each of the supported languages

Common Localization 030

Now that you have the needed files, it's time to localize only the text for the group panel. For that purpose, you need to create a single resource string in each one of the three resource files and translate it to the appropriate language.

Note that the name of the resource string should be the same as the resource key for the string that you are localizing. The resource key for RadGridView's group panel is GridViewGroupPanelText.

tipFor a full list of resource keys, check out the Localization topic for the specific control. <Comment: This is a repeat of the same tip in the last section. Is it important to repeat it?>

Figure 5 shows the content of the GridViewResources.de.resx file. The resource Name (GridViewGroupPanelText) of the other two files should be the same. The Value column will contain the translation for the appropriate language.

Figure 5: The content of GridViewResources.de.resx

Common Localization 040

The last step is to instantiate the LocalizationManager class, which allows you to easily localize any Telerik UI controls, by going through all resource keys and returning the appropriate translation. You then set its ResourceManager to the resources that have just been created (you can do this in the default constructor of the Application class).

{% if site.site_name == 'WPF' %}

[C#] Example 2: Setting the LocalizationManager's ResourceManager

{% endif %} {% if site.site_name == 'Silverlight' %}

[C#] Example 3: Setting the LocalizationManager's ResourceManager

{% endif %}

{{region common-localization_2}} LocalizationManager.Manager = new LocalizationManager() { ResourceManager = GridViewResources.ResourceManager }; {{endregion}}

{% if site.site_name == 'WPF' %}

[VB.NET] Example 2: Setting the LocalizationManager's ResourceManager

{% endif %} {% if site.site_name == 'Silverlight' %}

[VB.NET] Example 3: Setting the LocalizationManager's ResourceManager

{% endif %}

{{region common-localization_3}} LocalizationManager.Manager = New LocalizationManager() LocalizationManager.Manager.ResourceManager = GridViewResources.ResourceManager {{endregion}}

{% if site.site_name == 'WPF' %}

If you rely on culture settings to load the right resources automatically, you have to write some code inside your application's project file. For example, if you have to support English and Dutch languages, you can store the localized strings in Resources.resx and Resources.nl.resx files. For the Resources.resx file, you can set ResXFileCodeGenerator to Internal or Public and for others, to No code generation.
{% endif %}

{% if site.site_name == 'Silverlight' %}

If you rely on culture settings to load the right resources automatically, you have to write some code inside your application's project file. For example, if you have to support English and Dutch languages, you can store the localized strings in Resources.resx and Resources.nl.resx files. For the Resources.resx file, you can set ResXFileCodeGenerator to Internal or Public and for others, to No code generation. Then, open the project file in a text-mode and insert the code below into the <PropertyGroup> section. In this way you notify the framework about the supported cultures.

[XAML] Example 4: Setting the project's supported cultures

{{region common-localization_4}} en;nl {{endregion}} {% endif %}

Localization Using Custom Localization Manager

If you want to translate your controls to a language different from the default available ones, you will need to create a custom LocalizationManager. To do so, create a class that derives from LocalizationManager and override its GetStringOverride() method. The logic is pretty simple - you just have to create a switch statement and return the correct translation for each resource key, as shown below:

{% if site.site_name == 'WPF' %}

[C#] Example 3: Overriding the LocalizationManager's GetStringOverride() method

{% endif %} {% if site.site_name == 'Silverlight' %}

[C#] Example 5: Overriding the LocalizationManager's GetStringOverride() method

{% endif %}

{{region common-localization_5}} public class CustomLocalizationManager : LocalizationManager { public override string GetStringOverride(string key) { switch( key ) { case "GridViewGroupPanelText": return "Zum gruppieren ziehen Sie den Spaltenkopf in diesen Bereich."; //---------------------- RadGridView Filter Dropdown items texts: case "GridViewClearFilter": return "Filter löschen"; case "GridViewFilterShowRowsWithValueThat": return "Anzeigen der Werte mit Bedingung:"; case "GridViewFilterSelectAll": return "Alles anzeigen"; case "GridViewFilterContains": return "Enthält"; case "GridViewFilterEndsWith": return "Endet mit"; case "GridViewFilterIsContainedIn": return "Enthalten in"; case "GridViewFilterIsEqualTo": return "Gleich"; case "GridViewFilterIsGreaterThan": return "Grösser als "; case "GridViewFilterIsGreaterThanOrEqualTo": return "Grösser oder gleich"; case "GridViewFilterIsLessThan": return "Kleiner als"; case "GridViewFilterIsLessThanOrEqualTo": return "Kleiner oder gleich"; case "GridViewFilterIsNotEqualTo": return "Ungleich"; case "GridViewFilterStartsWith": return "Beginnt mit"; case "GridViewFilterAnd": return "Und"; case "GridViewFilter": return "Filter"; } return base.GetStringOverride(key); } {{endregion}}

{% if site.site_name == 'WPF' %}

[VB.NET] Example 3: Overriding the LocalizationManager's GetStringOverride() method

{% endif %} {% if site.site_name == 'Silverlight' %}

[VB.NET] Example 5: Overriding the LocalizationManager's GetStringOverride() method

{% endif %}

{{region common-localization_6}} Public Class CustomLocalizationManager Inherits LocalizationManager Public Overrides Function GetStringOverride(key As String) As String Select Case key Case "GridViewGroupPanelText" Return "Zum gruppieren ziehen Sie den Spaltenkopf in diesen Bereich." '---------------------- RadGridView Filter Dropdown items texts:' Case "GridViewClearFilter" Return "Filter löschen" Case "GridViewFilterShowRowsWithValueThat" Return "Anzeigen der Werte mit Bedingung:" Case "GridViewFilterSelectAll" Return "Alles anzeigen" Case "GridViewFilterContains" Return "Enthält" Case "GridViewFilterEndsWith" Return "Endet mit" Case "GridViewFilterIsContainedIn" Return "Enthalten in" Case "GridViewFilterIsEqualTo" Return "Gleich" Case "GridViewFilterIsGreaterThan" Return "Grösser als " Case "GridViewFilterIsGreaterThanOrEqualTo" Return "Grösser oder gleich" Case "GridViewFilterIsLessThan" Return "Kleiner als" Case "GridViewFilterIsLessThanOrEqualTo" Return "Kleiner oder gleich" Case "GridViewFilterIsNotEqualTo" Return "Ungleich" Case "GridViewFilterStartsWith" Return "Beginnt mit" Case "GridViewFilterAnd" Return "Und" Case "GridViewFilter" Return "Filter" End Select Return MyBase.GetStringOverride(key) End Function End Class {{endregion}}

Of course, if you don't want to hard-code your translation inside your source code, you can always use resource files:

{% if site.site_name == 'WPF' %}

[C#] Example 4: Using resource files in the GetStringOverride() method

{% endif %} {% if site.site_name == 'Silverlight' %}

[C#] Example 6: Using resource files in the GetStringOverride() method

{% endif %}

{{region common-localization_7}} public override string GetStringOverride(string key) { switch( key ) { //---------------------- case "GridViewClearFilter": return GridViewResources.GridViewClearFilter; //---------------------- } return base.GetStringOverride(key); } {{endregion}}

{% if site.site_name == 'WPF' %}

[VB.NET] Example 4: Using resource files in the GetStringOverride() method

{% endif %} {% if site.site_name == 'Silverlight' %}

[VB.NET] Example 6: Using resource files in the GetStringOverride() method

{% endif %}

{{region common-localization_8}} Public Overloads Overrides Function GetStringOverride(ByVal key As String) As String Select Case key '----------------------' Case "GridViewClearFilter" Return GridViewResources.GridViewClearFilter '----------------------' End Select Return MyBase.GetStringOverride(key) End Function {{endregion}}

All that's left to do is to set our CustomLocalizationManager to the static Manager property of the LocalizationManager:

{% if site.site_name == 'WPF' %}

[C#] Example 5: Applying the custom LocalizationManager

{% endif %} {% if site.site_name == 'Silverlight' %}

[C#] Example 7: Applying the custom LocalizationManager

{% endif %}

{{region common-localization_0}} LocalizationManager.Manager = new CustomLocalizationManager(); {{endregion}}

{% if site.site_name == 'WPF' %}

[VB.NET] Example 5: Applying the custom LocalizationManager

{% endif %} {% if site.site_name == 'Silverlight' %}

[VB.NET] Example 7: Applying the custom LocalizationManager

{% endif %}

{{region common-localization_1}} LocalizationManager.Manager = New CustomLocalizationManager() {{endregion}}

See Also

  • [Consuming Data - Overview]({%slug consuming-data-overview%})