Localization and Resource Kit

Users in Germany expect German dialog boxes, and users in France French ones. TX Text Control .NET for Windows Forms shows its dialog boxes and messages in English or German out of the box, and the Resource Kit adds other languages as satellite assemblies. Find out below how the language is chosen, what to ship for German, how a translation is built, and how your own buttons get the texts and icons of TX Text Control in a given language.

The language of the user interface is not the language of the document: which language a word is checked in is a formatting attribute of the text, set with LanguageDialog or in code, as Spell Checking describes.

What Is Translated

TX Text Control has built-in dialog boxes and error strings, which are .NET string resources. The texts of the ribbon are resources as well: the ResourceProvider returns them in the language you ask for, as shown at the end of this page. The file dialog boxes for loading and saving, on the other hand, are part of .NET, and their language depends on the language of the system.

The English resources are part of the assemblies. The German resources are satellite assemblies: separate assemblies that contain only the resources of one language. The NuGet package TXTextControl.TextControl.WinForms.SDK brings them in the folder lib/net8.0/de:

English and German are built in and can't be changed.

How the Language Is Chosen

TX Text Control follows the same mechanism as the .NET dialog boxes: its resources depend on the current system language. On a German system, the built-in dialog boxes and messages appear in German, provided that the folder de with the satellite assemblies is next to the TX Text Control assemblies. On a system with a language for which no satellite assembly exists, they appear in English.

The same applies to satellite assemblies of your own: a French satellite assembly is loaded only when the system language is French.

The culture also sets units: when DialogUnit is Auto, the dialog boxes show sizes and distances in the unit of the culture of the current thread. Built-in Dialog Boxes sets a fixed unit.

Ship the German Texts

When a .NET project is built, the folder de is copied into the output directory. Keep it there when you deploy the application:

<application folder>\YourApplication.exe
<application folder>\TXTextControl.dll
<application folder>\TXTextControl.Windows.Forms.dll
<application folder>\de\TXTextControl.resources.dll
<application folder>\de\TXDocumentServer.resources.dll
<application folder>\de\TXDrawing.resources.dll
<application folder>\de\TXBarcode.resources.dll

Without the folder, the dialog boxes and messages are English on every system. Managed Assemblies and Native Libraries lists all files an application ships.

Translate Into Another Language

The Resource Kit is installed by the setup in the ResourceKit folder of the TX Text Control installation directory. It contains:

The ribbon texts are in these resources too: the blog article Changing the Language in the Angular Document Editor Using the Resource Kit changes the name of the Reporting tab in TextControl.resx. It also mentions further .resx files, such as TXBarcode.resx, that are translated the same way.

A satellite assembly is built in these steps:

1. Install the .NET Framework SDK, whose tools buildres.bat calls.

2. Translate the text resources in TextControl.resx: change the content of each value element and keep the names of the resources.

3. Run the batch file in the ResourceKit folder with the two-letter ISO 639 code of the language, for example fr for French:

   .\buildres.bat fr
   

   It builds the satellite assembly txtextcontrol.resources.dll.

4. Create a subfolder named after the language code, such as fr, in the folder of your application that contains the TX Text Control files, and copy the satellite assembly into it:

   <application folder>\fr\txtextcontrol.resources.dll
   

5. Create a registry key on each machine so that the .NET Framework uses your own build of the satellite assembly with the application:

   HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\StrongName\Verification\txtextcontrol.resources,6B83FE9A75CFB638
   

   A 32-bit application on 64-bit Windows needs the same key below HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\StrongName\Verification. The documentation of the Resource Kit lists the keys for the other satellite assemblies in the same form: TXBarcode.resources, TXDocumentServer.resources, TXDrawing.resources and TXTextControl.resources, each followed by ,6B83FE9A75CFB638.

The Resource Kit and these steps are written for the .NET Framework: the batch file uses the .NET Framework SDK, and the registry key concerns the .NET Framework's check of strong names. The sources do not describe a different procedure for projects that target .NET 8 or higher. Deploying .NET Framework Applications covers the files of a .NET Framework application.

Get Texts and Icons in a Language

The ResourceProvider class returns the texts of the ribbon items in a language you choose, for buttons and menus of your own. GetText, GetToolTipTitle, GetToolTipDescription and GetKeyTip take an item identifier and, optionally, a CultureInfo that specifies the language of the returned text.

Some icons differ by language: the icons for bold, italic and underline, TXITEM_Bold, TXITEM_Italic and TXITEM_Underline, exist for English, French, German and Spanish. The Culture property of ImageSourceSettings selects them for GetSmallIcon. Its default is CultureInfo.CurrentUICulture, and English is used for a culture without its own icon.

The following method sets up a button of your own with the German text, tooltip and icon of the ribbon's Bold item:

using System.Globalization;
using System.Windows.Forms;
using TXTextControl.Windows.Forms;

private void SetUpBoldButton(Button boldButton)
{
    CultureInfo german = new CultureInfo("de");
    string identifier = TXTextControl.Windows.Forms.Ribbon.RibbonFormattingTab.RibbonItem.TXITEM_Bold.ToString();

    ResourceProvider.ImageSourceSettings settings = new ResourceProvider.ImageSourceSettings();
    settings.Culture = german;

    boldButton.Text = ResourceProvider.GetText(identifier, german);
    boldButton.Image = ResourceProvider.GetSmallIcon(identifier, textControl1, settings);
    new ToolTip().SetToolTip(boldButton, ResourceProvider.GetToolTipTitle(identifier, german));
}

The code works as follows:

• The identifier is the name of a value of RibbonFormattingTab.RibbonItem, converted with ToString. Every ribbon tab has such an enumeration.
• GetText and GetToolTipTitle return the German strings because a German CultureInfo is passed.
• ImageSourceSettings.Culture selects the German icon for bold. GetSmallIcon takes the resolution from textControl1, whose handle must have been created.

Next Steps

• Built-in Dialog Boxes: the dialog boxes whose texts are translated.
• Right-to-Left UI: the layout for Arabic and Hebrew.
• Themes, Colors, and Icons: more on the icons of the ResourceProvider.
• Managed Assemblies and Native Libraries: the files to deploy.