Soluling home   Document home

Delphi VCL

How to Localize Delphi and C++Builder VCL Applications

This tutorial shows how to localize your Delphi and C++Builder desktop VCL applications using Soluling.

Steps you need to do before your can localize

Before you can start localizing your application, you need to perform these two steps:

Once you have done the above steps, you can create a Soluling project file.

Create a project

Start Soluling. Click New from File or Files button in the main view or drag and drop your application's file (.exe/.dll/.bpl) on the main view. Soluling starts the Project Wizard that collects the information needed to create a new Soluling project. The first sheet of the wizard is the Options sheet.

Delphi options sheet of Project Wizard

We strongly recommend that you use a DRC file. If you don't have it abort the wizard, start Delphi, open your project and chnage the project settings to make Delphi to create the DRC file. Keep the default settings and click Next. The Resources sheet appears.

Delphi options sheet of Project Wizard

This sheet lets you select the resource types you want to localize. Most applications only need String and Form resources to be localized. Depending on your application, you might want to localize other resources, such as images and version resources. Click next. If you have existing localized files, Soluling detects them and shows the Import existing localized files sheet.

Delphi options sheet of Project Wizard

If you want to import the translations from the existing file, keep all checkbox checked and click Next. The Project file sheet appears.

Delphi options sheet of Project Wizard

Soluling localizes VCL applications from the binary file. So no source code is needed. However, if you have resource string comments, then Soluling needs to read also the source code files. To find the source code files, Soluling needs to know the location of the Delphi project file (.dpr). Check Scan source code to find resource string comments if you want to scan the comments. Click Next. The Select Languages sheet appears.

Delphi options sheet of Project Wizard

Add the languages you want to localize to. Later you can add new languages at any time. Soluling tries to detect your original language. If it is not right, select it from the list. If the original language is country-specific such as English (United States), you can make it country neutral by clicking the scissors icon. Click Finish to complete the wizard.

Delphi options sheet of Project Wizard

Now your project is created, and you can start translating it.

Translate the project

Follow the general translate instructions to translate your project. When you have translated the project, you can build the localized files.

Soluling has a visual form editor for VCL. It will be automatically shown when you select a form resource from the project tree. You can use the form editor to change the layout of the form. If you want to move or resize a control, use the mouse to select it. Then use either the mouse or keyboard to move or resize the selected item. If you use the mouse, drag the component to move it. To resize, drag one of its trackers. To move using the keyboard, press the Ctrl+arrow key. To resize, press the Shift+arrow key.

Fort editor

You can also change the layout properties (e.g., Left, Top, Width, Height) from the grid. However, by default, the grid does not show those properties. You have to turn them on. Right-click the grid and then select Filter. Select Data types sheet and check the Coordinate check box.

Delphi options sheet of Project Wizard

Now the grid shows the coordinate properties, and you can change them.

Windows 32-bit vs Windows 64-bit

VCL supports both 32-bit and 64-bit applications. You don't need a separate Soluling project for each application file variant, or you don't have to all variant files into the same project file. Add either 32-bit or 64-bit application file and then add the other files as platform files.

As a result, the 64-bit .exe has been added as a source and the 32-bit .exe as a platform file.

Delphi options sheet of Project Wizard

The advantage of the platform files over a separate project or two .exe files in a project is that you don't get multiple strings rows. If the same string exists both in 32-bit and 64-bit, only one row is added. This makes translation work easier. You can add any number of platform files. Just make sure that each EXE file you add is a result of the same Delphi project file. In addition to 32-bit, you might have Debug/Release EXEs or an EXE using different conditional compiling. Read more about the platform files.

Note! macOS application files have no file extension. For example Project1. If you want to add such as file, the file open dialog does not show them unless you select All files (*.*) filter in the file open dialog.

Build localized files

Soluling can create four kinds of localized files for your Delphi application or library. They are:

Method Description
Localized files

Default. Soluling creates copies from the original file, one for each language. The copies are identical to the original except the translated resource data have been modified. Use this if you know the language the user wants to use at the time he or she installs your application.

Language files Soluling creates a language resource DLL for each language. Use this if you want to make a multilingual installation where the user can choose the initial language or even change the language in runtime.
Multilingual file Soluling creates a single output file that is multilingual. It is easy to deploy, but the user can not choose the language the application appears. The active language depends on the language version of the user's operating system.
Embedded file

When building, Soluling first creates the resource DLL files into the output directory, copies the original application file to the same output directory, and finally adds all resource DLL files inside the application file as a custom SOLULING resource. When applications start for the first time, the Soluling code in your application extracts the resource DLL files and saves them on the disk. This makes it possible to make a single file deployment.

By default, Soluling creates localized files. You can configure Soluling to create any combination of the above files in the Output sheet.

Note! For macOS files only Localized files is available.

Delphi options sheet of Project Wizard

Choose the initial language and optionally implement runtime language change

If you choose Language or Embedded s output files, you can set the language your application uses when it starts. If you want to implement the runtime language change, follow these instructions.

Multi-project applications

If you have several Delphi projects that you want to localize, you have two options. The first option is to add each application/library file (.exe, .bpl, or .dll) into the same Soluling project. This is easy if you have a small number of projects. However, if you have a large number of projects and they all remain in a single RAD Studio Group file, it may be easier to create a Soluling project containing your RAD Studio Group file (.groupproj). In that case, there will be one roo level resource containing one sub source for each project in your group file.

RAD Studio Group file in a project tree

The above image shows the project tree of a Soluling project containing ProjectGroup1.groupproj source with two sub-sources: Project1.exe and Project2.exe. If you later add a third project to ProjectGroup1.groupproj, it will be automatically scanned next time you scan your Soluling project, and it will appear in the project tree.

Delphi 10.4.1 and 10.4.2

Delphi 10.4.1 has a bug that prevents loading resource string from a resource DLL. Fortunately, there is a workaround that Soluling's VCL API automatically applies. Delphi 10.4.2 fixes this bug by introducing System.SysUtils.ResStringCleanupCache that TNtBase.LoadNew in NtBase.pas calls. Soluling's API calls this before loading a new resource DLL. So if you use Delphi 10.4.1 or 10.4.2, make sure that you have the newest Soluling's VCL API.

Learn more

Read more about Delphi localization.