Localization of Syncfusion WF Controls

2 Nov 202221 minutes to read

Localization is the process of making application multilingual by formatting the content according to the cultures. This involves configuring the application for a specific language. Culture is the combination of language and location. For example, en-US is the culture for English spoken in United States; en-GB is the culture for English spoken in Great Britain.

Syncfusion components support localization and have their own neutral resources. These resources can be localized as per the customer requirement and they can be localized in three ways are,

• Using ILocalizationProvider
• Using Satellite Assemblies
• Using .resx file

Using ILocalizationProvider

The following procedure helps to localize the FindDialogBox in the Edit Control:

1. Include the required namespaces at the beginning of the source file.

   C#

   using Syncfusion.Windows.Forms;
   using Syncfusion.Windows.Forms.Edit;

   VB.NET

   Imports Syncfusion.Windows.Forms
   Imports Syncfusion.Windows.Forms.Edit

2. Create a class that implements the ILocalizationProvider interface defined in the Syncfusion.Windows.Forms namespace in the Syncfusion.Shared.Base.dll.

3. Return the localized versions of the strings corresponding to the string identifiers.

4. String identifiers are defined in the ResourceIdentifiers and the EditResourceIdentifiers classes in Syncfusion.Shared.Base and Syncfusion.Edit.Windows assemblies respectively.

   C#

   using Syncfusion.Windows.Forms.Localization.Localizer.EditResourceIdentifiers;
   using Syncfusion.Windows.Forms.ResourceIdentifiers;

   VB.NET

   Imports Syncfusion.Windows.Forms.Localization.Localizer.EditResourceIdentifiers
   Imports Syncfusion.Windows.Forms.ResourceIdentifiers

5. Leave an empty string for the rest of the identifiers that are not involved in the localization. These identifiers are loaded with a default value.

6. Assign this instance to the Provider property of the LocalizationProvider class before the InitializeComponent call in the constructor of the application.

   C#

   LocalizationProvider.Provider = new Localizer();

   VB.NET

   LocalizationProvider.Provider = New Localizer()

7. The following code example is a reference to assign Localization string

   C#

   public string GetLocalizedString(System.Globalization.CultureInfo culture, string name,object obj)
   {
       switch (name)
       {
           case Localizer.EditResourceIdentifiers.FDbtnClose:
                return "schließen";
           case Localizer.EditResourceIdentifiers.FDbtnFind:
                return "finden";
           case Localizer.EditResourceIdentifiers.FDbtnMarkAll:
                return "markieren Sie alle";
           case Localizer.EditResourceIdentifiers.FDchkCase:
                return "übereinstimmen Fall";
           case Localizer.EditResourceIdentifiers.FDchkHidden:
                return "Suche hidden";
           case Localizer.EditResourceIdentifiers.FDchkRegular:
                return "Suche regelmäßige";
           case Localizer.EditResourceIdentifiers.FDchkUp:
                return "Suche Up";
           case Localizer.EditResourceIdentifiers.FDchkWholeWord:
                return "Ganzes Wort";
           case Localizer.EditResourceIdentifiers.FDchkWrap:
                return "Zeilenumbruch";
           case Localizer.EditResourceIdentifiers.FDGroupTitle:
                return "Suchen";
           case Localizer.EditResourceIdentifiers.FDMain:
                return "Startseite";
           case Localizer.EditResourceIdentifiers.FDrdbDocument:
                return "Document";
           case Localizer.EditResourceIdentifiers.FDrdbSelection:
                return "Auswahl";
           case Localizer.EditResourceIdentifiers.FDTitle:
                return "Kommentar";
           default:
                return string.Empty;
       }
   }

   VB.NET

   Public Function GetLocalizedString(ByVal culture As System.Globalization.CultureInfo, ByVal name As String, ByVal obj As Object) As String
   	Select Case name
   		Case Localizer.EditResourceIdentifiers.FDbtnClose
   		     Return "schließen"
   		Case Localizer.EditResourceIdentifiers.FDbtnFind
   		     Return "finden"
   		Case Localizer.EditResourceIdentifiers.FDbtnMarkAll
   		     Return "markieren Sie alle"
   		Case Localizer.EditResourceIdentifiers.FDchkCase
   		     Return "übereinstimmen Fall"
   		Case Localizer.EditResourceIdentifiers.FDchkHidden
   		     Return "Suche hidden"
   		Case Localizer.EditResourceIdentifiers.FDchkRegular
   		     Return "Suche regelmäßige"
   		Case Localizer.EditResourceIdentifiers.FDchkUp
   		     Return "Suche Up"
   		Case Localizer.EditResourceIdentifiers.FDchkWholeWord
   		     Return "Ganzes Wort"
   		Case Localizer.EditResourceIdentifiers.FDchkWrap
   		     Return "Zeilenumbruch"
   		Case Localizer.EditResourceIdentifiers.FDGroupTitle
   		     Return "Suchen"
   		Case Localizer.EditResourceIdentifiers.FDMain
   		     Return "Startseite"
   		Case Localizer.EditResourceIdentifiers.FDrdbDocument
   		     Return "Document"
   		Case Localizer.EditResourceIdentifiers.FDrdbSelection
   		     Return "Auswahl"
   		Case Localizer.EditResourceIdentifiers.FDTitle
   		     Return "Kommentar"
   		Case Else
   		     Return String.Empty
   	End Select
   End Function

Using Satellite Assemblies

Localization is a key feature for providing solutions to global customers. This is true for desktop applications as well as Syncfusion components. Resources are important for localizing an application as they contain the necessary settings for different languages and cultures. Here Internationalization and localization are different but related concepts.

• Internationalization: Ensuring an application can handle resources (For example, strings) in a language-specific fashion. Internationalization is also known as i18n.

• Localization: Also known as l10n. Localization is the process of customizing an application for specific cultures or regions. It is the adaptation of language, content, and design to reflect the local cultural sensitivities.

Types of cultures

• Invariant: An invariant culture is always culture-insensitive primarily used as a “default” culture and helps to specify the invariant culture with name by using an empty string (“”). It is associated with the English language but not with any particular country or region.

• Neutral: A neutral culture is a culture that is associated with a language but not with a country or region.

• Specific: A specific culture is a culture that is associated with a language and a country or region like, fr-CA and fr-FR. For example, fr is a neutral culture and fr-FR is a specific culture. Note that zh-CHS (simplified Chinese) and zh-CHT (traditional Chinese) are neutral cultures.

Steps to Localize Syncfusion Components

Syncfusion components have their own neutral resources, and these resources can be localized as per the needs of the customer. The steps for localizing the Syncfusion Menu Package are as follows.

1. The neutral resources of every Syncfusion component are present in the Localization folder of each component’s source code. For the Tools package, the resources are present in the following path assuming that “C:\Program Files\” is the installation path for the Syncfusion components.

   • For Tools.Windows: C:\Program Files\Syncfusion\Essential Studio\26.2.4\Windows\Tools.Windows\Localization\

   • For Shared.Base: C:\Program Files\Syncfusion\Essential Studio\26.2.4\Base\Shared.Base\Localization

NOTE

In above section, Latest Essential Studio version details has been provided. User can refer installed Essential Studio version instead of mentioned version.

1. Inside the NeutralResources folder, there are four resource files corresponding to the Tools package. These resources contain the string representations for the English culture, both default and neutral.

2. Microsoft Visual Studio.NET ships with a tool called Resource Editor (ResEditor) that can be used to localize the string resources. It provides a graphical interface that allows to construct resource files containing bitmaps, icons, and strings.

3. Compile the source code by using the build.bat command in the Microsoft Visual Studio 2008 Command prompt. The following figure shows how the Resource Editor looks when it first opens.

1. By using the Resource Editor, open the resource file, Syncfusion.Windows.Forms.Tools.SR.resources present in the NeutralResources folder. The previous figure shows all string resources displayed in the tool.

2. Now, the actual process for localization begins. After opening the resource file in the Resource Editor, start entering the equivalent strings for the required culture. In this example, the German language is used. In the following figure, all the English strings are replaced by their German equivalent. For instance, the German equivalent of Close is “Ended”.

1. Open the Visual Studio.NET command prompt and enter WinRes to open the Windows Resource Localization Editor. WinRes is used to work with Windows Forms resources. The Resource Editor tool cannot be used to edit Windows Forms resources. It can only be used to work with images and string-based resources.

2. Open the other resources by using the WinRes utility and replace the English strings with the German equivalent. The following figure shows the file Syncfusion.Windows.Forms.Tools.XPMenus.CustomizationPanel.resources open in the WinRes tool and with German text. The German text has been added to the form by using the Properties window.

1. Click File -> Save As and select the culture to be localized. In this case, German-Germany. Now, a new resource file with the name Syncfusion.Windows.Forms.Tools.XPMenus.CustomizationPanel.de-DE.resources is added to the source path.

2. Repeat the process for other resources and save it. Now, in the Visual Studio.NET Command Prompt, enter the following command and press Enter. Make sure that sf.public snk file is available from the Localization folder.

For Tools.Windows

CONSOLE

al /t:lib /culture:de-DE /out:Syncfusion.Tools.Windows.resources.dll /v:19.1.0.54 /delay+ /keyf:sf.publicsnk /embed:Syncfusion.Windows.Forms.Tools.XPMenus.CustomizationPanel.de-DE.resources /embed:Syncfusion.Windows.Forms.MdiWindowDialog.de-DE.resources /embed:Syncfusion.Windows.Forms.Tools.SR.de-DE.resources /embed:Syncfusion.Windows.Forms.Tools.XPMenus.BarCustomizationDialog.de-DE.resources

For Shared.Base

   <div class="tabs">
   
   <ul class="nav nav-tabs" role="tablist">
   
   <li role="presentation" class=""><a data-target="#s9ceahh5l613iu7ypfvvysi72jn8a1iu-console" aria-controls="home" role="tab" data-toggle="tab" data-original-lang="console">CONSOLE</a></li>
   
   </ul>
   
   <div class="tab-content">
   
   
   
   <div role="tabpanel" class="tab-pane" id="s9ceahh5l613iu7ypfvvysi72jn8a1iu-console" data-original-lang = "console" ><div class="highlight"><pre><code class="language-console" data-lang="console"><span></span><span class="go">al /t:lib /culture:de-DE /out:Syncfusion.Shared.Base.resources.dll /v:19.1.0.54 /delay+ /keyf:sf.publicsnk /embed: Syncfusion.Windows.Forms.Localization.SR.de-DE</span></code></pre></div>
   </div>
   
   
   </div>
   
   </div>

1. On successful execution, an assembly file, Syncfusion.Tools.Windows.resources.dll is created.

2. Finally, mark this satellite assembly for verification skipping since, it is not signed with the same strong-name as the product assembly as follows:

CONSOLE

sn –Vr Syncfusion.Tools.Windows.resources.dll

1. Drop this assembly into an appropriate sub-directory under .EXE’s directory (bin\Debug), based on the naming conventions enforced in .NET. and it can placed in the de-DE sub-directory when this assembly contains resources from the German (Germany) culture.

2. Finally, application can refer German resources during runtime by using the following code example. To change the UI culture of the current thread, add this code in the Forms constructor before the InitializeComponent().

C#

Thread.CurrentThread.CurrentUICulture = new System.Globalization.CultureInfo("de-DE");

VB.NET

Thread.CurrentThread.CurrentUICulture = New System.Globalization.CultureInfo("de-DE")

1. Now, Run the application that contains the Syncfusion Toolbar and Menu controls and open the Customization dialog. The dialog appears in German as shown in the following figure:

Localize Syncfusion Windows Forms control using .resx file

You can localize the syncfusion Windows Forms Controls by adding resource file for each language.

Changing application culture

When you are changing the application culture, then you can localize the application based on application culture by creating .resx file.

C#

public partial class Form1 : Form
{
    public Form1()
    {
        Thread.CurrentThread.CurrentCulture = new System.Globalization.CultureInfo("de-DE");
        Thread.CurrentThread.CurrentUICulture = new System.Globalization.CultureInfo("de-DE");
        InitializeComponent();
    }
}

VB.NET

Partial Public Class Form1
	Inherits Form
	Public Sub New()
		Thread.CurrentThread.CurrentCulture = New System.Globalization.CultureInfo("de-DE")
		Thread.CurrentThread.CurrentUICulture = New System.Globalization.CultureInfo("de-DE")
		InitializeComponent()
	End Sub
End Class

Creating .resx files

You can create .resx files for any languages by following steps,

NOTE

You can get the default resource files of all Syncfusion Windows Forms libraries from View resource files in GitHub

1. Right click your project and click New Folder and set name as Resources.

2. Add Windows Forms Control Localization default resource files of libraries you are using into Resources folder.

NOTE

Consider you are using SfDataGrid control in your application. Then you need to copy and include Syncfusion.SfDataGrid.WinForms.resx (SfDataGrid present in Syncfusion.SfDataGrid.WinForms library) file in your application under Resources folder. So, now you can know the key names and values of default strings used in Syncfusion.SfDataGrid.WinForms.dll library.

1. Now, right click on Resources folder and select Add and then New Item. In the Add New Item wizard, select Resources File option and name the file name as Syncfusion.SfDataGrid.WinForms.<culture name>.resx for German culture. For example, you have to give name as Syncfusion.SfDataGrid.WinForms.de-DE.resx for German culture. In the same way, add new resource files for other libraries used in your application.

1. Now, select Add and add resource file for German culture in Resources folder.

1. Now, you can copy the key names from default resource files and change its corresponding value based on the culture.

NOTE

Download demo from View sample in GitHub.

Localize when resource file is present in different namespaces or assemblies

The below table represents that how the resource file need to set if we using our syncfusion controls from different assembly or namespace,

Control Assembly	Code Snippet
Syncfusion.Diagram.Windows	DiagramLocalizationResourceAccessor.Instance.SetResources(assembly, "namespace");
Syncfusion.Edit.Windows	EditLocalizationResourceAccessor.Instance.SetResources(assembly, "namespace");
Syncfusion.Grid.Windows	GridLocalizationResourceAccessor.Instance.SetResources(assembly, "namespace");
Syncfusion.Grid.Grouping.Windows	GridGroupingLocalizationResourceAccessor.Instance.SetResources(assembly, "namespace");
Syncfusion.HTMLUI.Windows	HtmlUILocalizationResourceAccessor.Instance.SetResources(assembly, "namespace");
Syncfusion.PdfViewer.Windows	PdfViewerLocalizationResourceAccessor.Instance.SetResources(assembly, "namespace");
Syncfusion.PivotAnalysis.Windows.	PivotAnalysisLocalizationResourceAccessor.Instance.SetResources(assembly, "namespace");
Syncfusion.PivotChart.Windows	PivotChartLocalizationResourceAccessor.Instance.SetResources(assembly, "namespace");
Syncfusion.SfDataGrid.WinForms	DataGridLocalizationResourceAccessor.Instance.SetResources(assembly, "namespace");
Syncfusion.SfListView.WinForms	ListViewLocalizationResourceAccessor.Instance.SetResources(assembly, "namespace");
Syncfusion.SfSmithChart.WinForms	SmithChartLocalizationResourceAccessor.Instance.SetResources(assembly, "namespace");
Syncfusion.Spreadsheet.Windows	SpreadsheetLocalizationResourceAccessor.Instance.SetResources(assembly, "namespace");
Syncfusion.Shared.Base	SharedLocalizationResourceAccessor.Instance.SetResources(assembly, "namespace");
Syncfusion.Tools.Windows	ToolsLocalizationResourceAccessor.Instance.SetResources(assembly, "namespace");

And below steps helps you to show how localization can be done at different assemblies or namespaces,

1. Create a .resx files.

2. And add the below code in windows form constructor.

   C#

   public partial class Form1 : Form
   {
       public Form1()
       {
           Thread.CurrentThread.CurrentCulture = new System.Globalization.CultureInfo("de-DE");
           Thread.CurrentThread.CurrentUICulture = new System.Globalization.CultureInfo("de-DE");
           DataGridLocalizationResourceAccessor.Instance.SetResources(GetType().Assembly, "Localization");
           InitializeComponent();
       }
   }

   VB.NET

   Partial Public Class Form1
   	Inherits Form
   	Public Sub New()
   		Thread.CurrentThread.CurrentCulture = New System.Globalization.CultureInfo("de-DE")
   		Thread.CurrentThread.CurrentUICulture = New System.Globalization.CultureInfo("de-DE")
           DataGridLocalizationResourceAccessor.Instance.SetResources([GetType]().Assembly, "Localization")
   		InitializeComponent()
   	End Sub
   End Class

3. Then right click the project and create another windows form project named as WindowsFormsApp1.

4. In that project add the button and show the Localization Form in button click event as given below,

   C#

   using Localization;
   using System;
   using System.Windows.Forms;
      
   namespace WindowsFormsApp1
   {
       public partial class Form2 : Form
       {
           public Form2()
           {
               Button button = new Button();
               button.Click += button1_Click;
               this.Controls.Add(button);
               InitializeComponent();
           }
      
           private void button1_Click(object sender, EventArgs e)
           {
               Form1 form1 = new Form1();
               form1.Show();
           }
       }
   }

   VB.NET

   Imports Localization
   Imports System
   Imports System.Windows.Forms
      
   Namespace WindowsFormsApp1
       Public Partial Class Form2
           Inherits Form
      
           Public Sub New()
               Dim button As Button = New Button()
               button.Click += AddressOf button1_Click
               Me.Controls.Add(button)
               InitializeComponent()
           End Sub
      
           Private Sub button1_Click(ByVal sender As Object, ByVal e As EventArgs)
               Dim form1 As Form1 = New Form1()
               form1.Show()
           End Sub
       End Class
   End Namespace

5. Now, set startup project as WindowsFormsApp1 and run the project.

6. Then click the button Appeared in Form. Now, you can see that the text in SfDatagrid gets localized.

Editing default culture settings

You can change the default string of any control by adding the default .resx files (from GitHub) to Resources folder of your application. Syncfusion Windows Forms controls reads the default string from the .resx files of application if its added.