How to: Localize an Application

• Feb 18, 2022
• 6 minutes to read

This tutorial describes how to localize the TcxDateEdit control’s buttons and a form’s caption in German.

Prepare Localized Strings

DevExpress VCL controls use built-in resource strings to display captions, labels, and hints. You can translate these strings or create new strings in the Localizer Editor to localize an application.

Add Language Support

The Localizer Editor allows you to translate specific resource strings to different languages. Follow the steps below to add support for German:

1. Run the Localizer Editor application.

2. Open the File menu and select New to create a new resource string file.

   

3. Open the Languages menu and click Add… to invoke the Choose Languages dialog.

   

4. Check the German (Germany) item and click the OK button to add support for German to the file.

   

Translate Built-in Resource Strings

Define the following resource strings for German in the Localizer Editor to localize the TcxDateEdit control’s buttons:

Resource String	Original Value	Translated Text
cxSDatePopupClear	‘Clear’	‘Löschen’
cxSDatePopupNow	‘Now’	‘Jetzt’
cxSDatePopupToday	‘Today’	‘Heute’

Note

Names of months and days of the week in the TcxDateEdit control depend on the current system locale. You cannot translate these names with built-in or custom resource strings.

To translate a resource string to German, find the string in the grid and specify the translated text in the Resource String Value column located in the German (Germany) band.

Note

You can press the Ctrl+F keystroke to show the Find panel and search specific resource strings. You can also use the Filter box to filter resource strings by values in specific columns.

When you translate a resource string, the corresponding check box in the Translated column becomes checked. You can uncheck the check box to restore the string’s default value.

Create a Custom Resource String

The Localizer Editor allows you to create custom resource strings for captions and labels in an application. Perform the following actions to specify a custom resource string for the form’s caption:

1. Open the Custom Resource Strings menu and select Add to add an empty data row to the grid.

2. Specify the sAppName name for the created string in the Resource String Name column.

3. Enter the ‘Localization Demo’ and ‘Lokalisierung Demo’ strings in the Resource Strings band’s Original Value column and the German (Germany) band’s Resource String Value column, respectively.

Save Localized Strings

You can save localized resource strings as an INI or RES file to use them in an application. Refer to subsequent sections for information on how to load saved strings to an application.

To an INI File

To save localized strings as an INI file, open the File menu, click Save, and specify the target file in the invoked Save As dialog. If you save custom resource strings for the first time, the Localizer Editor additionally asks you to create a PAS file. This file contains Delphi code that registers new resource strings.

Save localized resource strings as the project folder’s Languages.ini and LocalizationDemoUnit.pas files.

The following example shows the Languages.ini file’s content:

[1031]
cxSDatePopupClear="Löschen"
cxSDatePopupNow="Jetzt"
cxSDatePopupToday="Heute"
sAppName="Lokalisierung Demo"

[Custom Resource Strings]
sAppName="Localization Demo"

Note

The number 1031 in square brackets indicates the German (Germany) locale.

The following example shows the LocalizationDemoUnit.pas file’s content:

unit LocalizationDemoUnit;

{$I cxVer.inc}

interface

uses
  dxCore;

resourcestring
  sAppName = 'Localization Demo';

implementation

procedure AddResourceStringNames(AProduct: TdxProductResourceStrings);
begin
  AProduct.Add('sAppName', @sAppName);
end;

initialization
  dxResourceStringsRepository.RegisterProduct('Custom Resource Strings', @AddResourceStringNames);

finalization
  dxResourceStringsRepository.UnRegisterProduct('Custom Resource Strings');

end.

To a RES File

Save localized resource strings to the project folder’s Languages.res file. To save localized strings as a RES file, open the File menu, click Build Resource File…, and specify the target file in the invoked Save As dialog.

Create a PAS file as described above to use custom resource strings.

Apply Localization

The TcxLocalizer component allows you to apply the stored localization from a file or resource.

Load Resource Strings

You can load resource strings from an INI file or a resource.

From an INI File

Follow the steps below to use the Languages.ini file to localize built-in resource strings:

1. Place the TcxLocalizer component on the form.

2. Select the component in the Object Inspector and set the StorageType property to lstIni.

3. Specify the path to the Languages.ini file in the FileName property.

4. Assign True to the Active property.

5. Select German (Germany) in the Locale property.

   

   Note

   The Locale property’s default value (0) corresponds to the English (Original translation) locale. This value indicates that the TcxLocalizer uses resource strings from DevExpress VCL libraries. These strings do not correspond to any specific locale.

From a Resource

Perform the following actions to apply localization of built-in resource strings from a resource linked to the Languages.res file:

1. Place the TcxLocalizer component on the form.

2. Select the component in the Object Inspector and set the StorageType property to lstResource.

3. Assign True to the Active property.

   

4. Specify the Languages.res resource file in the implementation clause of a module (in Delphi) or in a source file (in C++Builder).

   Delphi

   implementation
   {$R Languages.res} 
   

   C++

   #pragma resource "Languages.res" 
   

5. Set the TcxLocalizer.Locale property to 1031 in the form’s OnCreate event handler to load the German (Germany) locale at startup.

   Delphi

   procedure TForm1.OnCreate(Sender: TObject);
   begin
     cxLocalizer1.Locale := 1031;
   end; 
   

   C++

   void __fastcall TForm1::OnCreate(TObject *Sender)
   {
     cxLocalizer1->Locale = 1031;
   } 
   

   Note

   You can apply localization from a resource only at runtime.

Use a Custom Resource String

You can use custom resource strings to translate an application. Perform the following actions to translate the form’s caption:

1. Add LocalizationDemoUnit to the uses clause if you use Delphi. If you use C++Builder, add the LocalizationDemoUnit.pas file to the project, build it, and insert the created LocalizationDemoUnit.hpp file as an #include directive into the header file.

   Delphi

   uses
     LocalizationDemoUnit;
   

   C++

     #include "LocalizationDemoUnit.hpp"; 
   

2. Specify the IdxLocalizerListener interface in the form’s class declaration.

   Delphi

   type
     TForm1 = class(TForm, IdxLocalizerListener)
   

   C++

   class TForm1 : public TForm, IdxLocalizerListener     
   

3. Assign the sAppName resource string’s value to the form caption in the form’s TranslationChanged procedure.

   Delphi

   procedure TForm1.TranslationChanged;
   begin
     Caption := cxGetResourceString(@sAppName);
   end;
   

   C++

   void __fastcall TForm1::TranslationChanged()
   {
     Caption = cxGetResourceString(&_sAppName);
   }
   

4. Register and unregister the form as a localization change listener in the form’s constructor and destructor, respectively. Call the TranslationChanged procedure in the constructor to reload the locale.

   Delphi

   constructor TForm1.Create(AOwner: TComponent);
   begin
     inherited Create(AOwner);
     dxResourceStringsRepository.AddListener(Self);
     TranslationChanged;
   end;
   
   destructor TForm1.Destroy;
   begin
     dxResourceStringsRepository.RemoveListener(Self);
     inherited;
   end;
   

   C++

   __fastcall TForm1::TForm1(TComponent *AOwner) : TForm(AOwner)
   {
     dxResourceStringsRepository()->AddListener(this);
     TranslationChanged();
   }
   
   void __fastcall TForm1::~TForm1()
   {
     dxResourceStringsRepository()->RemoveListener(this);
   } 
   

   Note

   You can omit a TranslationChanged procedure call if you specify the application locale at runtime or use only built-in resource strings.

5. If you use C++Builder, add the following private members to the form class to support Delphi interfaces:

   private:
     LONG m_cRef;
   
     ULONG __stdcall AddRef()
     {
       return InterlockedIncrement(&m_cRef);
     };
   
     ULONG __stdcall Release()
     {
       return InterlockedDecrement(&m_cRef);
     };
   

The following image shows the result: