Delphi VCL

Delphi VCL Localization

Localize a Delphi or C++Builder VCL application from the compiled file, without the source code: Soluling reads the forms and resource strings of your .exe, lets you translate them in a visual form editor, checks the translations and the layout, and builds the localized files.

The steps are the same for Delphi and C++Builder. This guide uses the Driving sample, a small driving time calculator, and takes it from an English-only application to one that speaks Finnish, German, and Japanese and can change its language while it runs.

Download Soluling

You build EXE Driving.exe Soluling 150 60 Driving Time Driving distance: Speed: Round time Calculate Fahrzeit Fahrstrecke: Geschwindigkeit: Ungefähre Uhrzeit Berechnen The dialog as it is in the EXE has been translated in the visual editor You ship EXE Driving.exe fi fi\Driving.exe de de\Driving.exe ja ja\Driving.exe A localized Driving.exe in each language folder, or resource DLLs You build EXE Driving.exe Soluling 150 60 Driving Time Driving distance: Speed: Round time Calculate Fahrzeit Fahrstrecke: Geschwindigkeit: Ungefähre Uhrzeit Berechnen The dialog as it is in the EXE has been translated in the visual editor You ship EXE Driving.exe fi fi\Driving.exe de de\Driving.exe ja ja\Driving.exe A localized Driving.exe in each language folder, or resource DLLs
Deploy the original application with a resource DLL for each language, so one installation holds every language. Or deploy the localized application of one language (the default output).
Input
Application or library file (.exe, .dll, .bpl) and its .drc file, or a RAD Studio project group (.groupproj)
Output
Localized files (fi\Driving.exe), resource DLLs (Driving.fi), a multilingual file, or an embedded file
Runtime
The VCL loads the resource DLL of the user's language; Soluling's library adds the initial language and a runtime language switch
Preview
Visual form editor that shows the forms in each language and lets you move and resize controls

On this page

Tutorial

Localize a VCL application, step by step

Six steps take the Driving sample from a hard-coded English application to localized files.

01

Prepare: make the application localizable

The VCL stores forms as resources in the compiled file, so the forms are ready for localization as they are. The strings in the code are not. The original Driving application writes its result like this:

HoursLabel.Caption := IntToStr(hours) + ' hours';
MinutesLabel.Caption := IntToStr(minutes) + ' minutes';

Internationalizing the application takes three changes:

  1. Move the strings from code to resource strings. Declare them with resourcestring. The compiler stores them as string resources, and Soluling localizes them with the forms. A comment before a resource string is shown to the translator.
  2. Use one pattern for sentences with numbers. Don't build a sentence from pieces. The Driving sample stores the whole result as a plural pattern and formats it with TMultiPattern.Format from Soluling's Delphi library. See patterns.
  3. Create a DRC file. In Delphi, choose Project | Options | Linking and check Output resource string .drc file; in C++Builder, add the -GD linker option. The DRC file gives each resource string its name, such as SResultPlural, so translations stay with their strings when the code changes.
Moving hard-coded strings to a resource string pattern The hard-coded hours and minutes strings stay English and are not plural aware. After internationalizing, the code formats the SResultPlural resource string, which has English and Finnish plural patterns. Before: Original\Unit1.pas HoursLabel.Caption := IntToStr(hours) + ' hours'; MinutesLabel.Caption := IntToStr(minutes) + ' minutes'; ✕ Stays English, no plural forms Internationalize After: Localized\Unit1.pas resourcestring SResultPlural = 'Driving time{plural, one { %d hour } other { %d hours }}{plural, one {%d minute} other {%d minutes}}.'; ... ResultLabel.Caption := TMultiPattern.Format(SResultPlural, [hours, minutes]); Unit1.SResultPlural in Soluling SResultPlural English Driving time{plural, one { %d hour } other { %d hours }}{plural, one {%d minute} other {%d minutes}}. Finnish Ajoaika{plural, one { %0:d tunti } other { %0:d tuntia }}{plural, one {%0:d minuutti} other {%0:d minuuttia}}. ✓ Translated with the forms, with the plural forms of each language
The sample's real pattern also has a zero form for the hours, so "0 hours" is left out. Plural forms are simplified here.
02

Add: create a Soluling project

Compile the application in Delphi, then drag and drop the .exe on Soluling. Project Wizard starts. Soluling localizes the compiled file, so it doesn't need the source code.

  • On the Options page, keep the default settings, which use the DRC file.
  • On the Resources page, select the resource types. Most applications need only Strings and Forms; you can add images, version information, and others.
  • If the application has been localized before, Soluling finds the existing localized files and imports their translations.
  • On the Project file page, check Scan source code to find resource string comments to show your comments to the translator. Soluling needs the .dpr file for this.
  • On the Select Languages page, add the target languages, and click Finish.

Several applications and packages? Add each .exe, .dll, and .bpl to the same project, or add the RAD Studio project group (.groupproj), and Soluling picks up new projects of the group automatically. Do you build both 32-bit and 64-bit? Add one of them, and the other as a platform file, so each string is translated only once.

Project Wizard Driving.exe and its DRC file go through Project Wizard's Options page, Resources page (Strings and Forms selected), Project file page (scan source code for comments), and Select Languages page (Finnish, German, Japanese). Drop Driving.exe Driving.drc Options Use the DRC file ✓ Default Resources ☑ Strings ☑ Forms ☐ Images, Version, ... Project file Driving.dpr ☑ Scan comments Languages Finnish (fi) German (de) Japanese (ja) If Soluling finds existing localized files, a page to import them appears before Project file.
03

Translate: in the grid and the visual form editor

Each form appears in the project tree with its properties in the grid, and the resource strings under their units. Select a form, and the visual form editor shows it in the selected language. Selecting a row highlights its control. If a translation does not fit, move or resize the control with the mouse or the keyboard, for this language only.

  • Machine translation and translation memory. Click Use Machine Translation to translate with Amazon, Claude, DeepL, Google, Microsoft, ModernMT, or MyMemory, and reuse earlier translations from translation memory and terminology.
  • External translators. Send a translation package, an Excel file, or XLIFF to a translator, and import the results back. See teamwork.
  • Translators in a browser. Upload the project to Soluling Cloud and let translators work in Translate.
The translation grid and the visual form editor The grid lists the TFORM1 properties with Finnish translations. The selected row, DistanceLabel, is highlighted on the Finnish form in the visual editor. Grid: TFORM1 Context English Finnish Caption Driving Time Ajoaika File1.Caption File Tiedosto DistanceLabel.Caption &Driving distance: &Ajomatka: SpeedLabel.Caption &Speed: &Nopeus: CalculateAction.Caption Calculate Laske ResultLabel (set in code) Visual form editor: Finnish Ajoaika FI ✕ Tiedosto Ohje Ajomatka: 220 Nopeus: 88 Laske Ajoaika 2 tuntia 30 minuuttia. FI
The & marks the hotkey. Soluling keeps it in the translation and checks that hotkeys are not duplicated.
04

Check: find problems before release

Pseudo translation. Click Translate | Pseudo Translations | Fill, build, and run the application. Pseudo translations are longer and use accented characters, so texts that don't fit and strings still in the code (shown in plain English) stand out. See pseudo translation.

Pseudo-translated Original build

[Ðŕîvîñĝ Ţîɱé ___] PS ✕ [Ƒîļé __] [Ĥéļþ __] [Ðŕîvîñĝ ðîšţåñçé: ____________________] 220 [Šþééð: __________] 88 [Çåļçûļåţé ___] 2 hours 30 minutes PS Too long and still English (hard-coded)

Validation. Soluling validates translations while you type and in batch (Validation | Validate Translations): missing translations, inconsistent placeholders and patterns, duplicate hotkeys, and more. It also checks the layout of the localized forms: clipped text, overlapping controls, and controls outside their parent. See validation.

Validation: German

⚠ Inconsistent format string Unit1.SResultPlural Original uses one %d in each plural form; the translation uses %1:d: ... {plural, one {%1:d Minute} other {%1:d Minuten}} ⚠ Duplicate hotkey &Fahrstrecke: / &Fahrzeit berechnen Both use Alt+F on the same form, so change one of them. ⚠ Clipped text SpeedLabel: Geschwindigkeit: The label is wider than the space next to the button. Move or resize it in the form editor.
05

Build: create the localized files

Choose Home | Build All, and Home | Run Localized to start the application in a target language. On the Output sheet of the source, choose any combination of four kinds of output:

  • Localized files (the default): a copy of the application for each language, identical to the original except for the translated resources. Use these when you know the user's language when you install.
  • Resource DLLs: a resource-only DLL for each language, named after the application with the language code as the extension, such as Driving.fi. One installation holds every language; the user can choose the language and even change it at runtime.
  • Multilingual file: one application that contains every language. The language of the operating system decides which one is used.
  • Embedded file: the resource DLLs inside the application as a custom resource, extracted when the application first starts, for a single-file deployment with every language.
The four kinds of output Localized files: a complete Driving.exe in the fi, de, and ja folders. Resource DLLs: Driving.fi, Driving.de, and Driving.ja next to the original Driving.exe. Multilingual file: one Driving.exe with every language. Embedded file: one Driving.exe with the resource DLLs inside. Localized files (default) DIR Win32\Release\ EXE Driving.exe original, English fi fi\Driving.exe de de\Driving.exe ja ja\Driving.exe Resource DLLs DIR Win32\Release\ EXE Driving.exe original, unchanged DLL Driving.fi DLL Driving.de DLL Driving.ja Multilingual file DIR Win32\Release\all\ EXE Driving.exe every language; the operating system language decides Embedded file DIR Win32\Release\ EXE Driving.exe resource DLLs inside, extracted at the first start
Keep the resource DLLs next to the application, or tell the application where they are with TNtBase.SetResourceDllDir.
06

Update: translate only what changed

When the application changes, compile it in Delphi and click Home | Scan. Soluling compares the new forms and resource strings with the project, keeps the existing translations, adds the new strings, and marks the rows whose original text changed so that their translations are checked again. Rows are matched by their context, the component and property name or the resource string name, so keep them stable. Translate the new rows and build again.

You can automate the scan and build steps in your build pipeline with the SoluMake command-line tool.

Reference

Forms and resource strings are resources of the compiled file

The Delphi compiler stores every form (.dfm) as an RCDATA resource and every resource string as a Windows string resource in the .exe, .dll, or .bpl. Soluling reads them from the compiled file and writes the translated resources into the localized files or resource DLLs; the code is never changed. The DRC file gives the string resources their names.

Because sizes and positions are form properties too, a translation can have its own layout: if German needs a wider label, resize it in the visual form editor for German only. The layout validations find clipped text, overlapping controls, and controls outside their parent.

Initial language

When a VCL application starts, the VCL looks for a resource DLL in this order and loads the first one it finds. If there is none, the application uses its own resources.

How a VCL application chooses its resource DLL First the locale override in the registry, then the resource DLL of the specific locale, such as Driving.fi-FI, then the language, such as Driving.fi, and finally the original resources of Driving.exe. Locale override Registry entry for the application Specific locale Driving.fi-FI not shipped Language Driving.fi ✓ Loaded Original Driving.exe English resources Ship the language DLL (Driving.fi); it serves every Finnish locale.

Since Delphi 2010, the VCL chooses by the language of the operating system's user interface. To choose by the user's locale instead, as older Delphi versions did, add NtInitialLocale as the first unit of the project. A resource DLL contains every resource, so a string that is not translated is shown in the original language.

program Multilingual;

uses
  NtInitialLocale,
  Forms,
  Unit1 in 'Unit1.pas' {Form1};

Change the language at runtime

With resource DLLs or an embedded file, Soluling's Delphi library can change the language while the application runs. TNtLanguageDialog.Select from NtLanguageDlg shows the languages that have a resource DLL, loads the selected one, and translates the open forms. Properties that the code sets are not in the form resources, so set them again after the switch:

// Unit1.pas in the Multilingual version of the Driving sample
procedure TForm1.Language1Click(Sender: TObject);
begin
  // Show a language select dialog and turn on the selected language
  if TNtLanguageDialog.Select('en', 'English') then
  begin
    // Properties that were set at runtime must be set again
    CalculateActionExecute(Self);
  end;
end;
Runtime language switch The English Driving Time form, the Select Language dialog with English, Suomi, Deutsch, and Japanese, and the same form in Finnish without restarting. Driving Time EN ✕ File Help Driving distance: 220 Speed: 88 Calculate Driving time 2 hours 30 minutes. EN Select Language English suomi Deutsch 日本語 OK Ajoaika FI ✕ Tiedosto Ohje Ajomatka: 220 Nopeus: 88 Laske Ajoaika 2 tuntia 30 minuuttia. FI Same form, no restart

Translate in Soluling Cloud

With Soluling Cloud, translators use Translate in a browser. How you start depends on what you localize:

  • Delphi applications. Soluling Cloud can't scan a Delphi application file itself. Create the project in Soluling Desktop, and choose Translate | Configure Cloud to upload it. Use Import from Cloud to get the translations back and build the localized files locally. Your application files never leave your machine.

To run the scan, upload, import, and build steps in your build pipeline, use SoluMake. See the Cloud tutorial and workflows.

Do and don't

Do

  • Use resourcestring for every string the user sees.
  • Create the DRC file, so the resource strings keep their names.
  • Store whole sentences with placeholders, and use plural patterns for numbers.
  • Comment resource strings that need context, and let Soluling scan the comments.
  • Use AutoSize, anchors, and enough space for longer text.
  • Pseudo-translate before the first real translation.

Don't

  • Use string constants (const) for UI text; they are not resources.
  • Build sentences from pieces, such as IntToStr(hours) + ' hours'.
  • Rename components without a reason; renamed rows lose their translations.
  • Add the 32-bit and the 64-bit file as separate sources; use platform files.
  • Rename the resource DLLs; the extension must be the language code.

Typical localizability problems

See also internationalization and pseudo translation.

Problem How it shows Find and fix
Strings in code English text in a pseudo-translated build Move the strings to resourcestring sections.
No DRC file Resource strings have numeric contexts that change when the code changes Turn on Output resource string .drc file, compile, and scan.
Sentences built from pieces Word order and plurals are wrong in the translation Use one string with placeholders, or a plural pattern.
Controls only fit English Clipped text in the pseudo or German build Validation finds clipped and overlapping controls; resize them per language in the visual form editor.
Hotkeys collide Alt+letter selects the wrong control Validation finds duplicate hotkeys.

Troubleshooting

Symptom Likely cause What to do
The application stays in English No resource DLL matches the language, or it is not next to the application Check the file name (Driving.fi) and folder, or call TNtBase.SetResourceDllDir. Add NtInitialLocale to choose by the user's locale.
The application starts in the wrong language A locale override in the registry Remove the override, or let the user choose the language with TNtLanguageDialog.
Some texts stay in English after a runtime language switch The code sets those texts Set them again after TNtLanguageDialog.Select returns True.
A 3rd party component's property is not in the project The scan rules don't include it, or the component stores it in a proprietary format Check the scan rules; send us a sample if the format is unknown.
Resource strings fail to load on Delphi 10.4.1 A bug in Delphi 10.4.1 Use the newest version of Soluling's Delphi library, which works around it.

The Driving sample

The sample is in Samples\Delphi\VCL\Driving of the Soluling installation and on GitHub. It has three projects of the same application:

  • Original: the English application before internationalization, with hard-coded strings.
  • Localized: internationalized, with resource strings, plural patterns, and translations.
  • Multilingual: as above, with an initial language and a runtime language switch.

The Samples\Delphi\VCL folder has many more samples, for example, 3rd party components, single-file deployment, and layout checking. See VCL localization and Delphi localization in the Desktop documentation for all the details.

FAQ

No. Soluling reads the forms and resource strings from the compiled .exe, .dll, or .bpl. It reads the source code only if you want your resource string comments shown to the translator.

Use localized files if you install one language for each user. Use resource DLLs, or an embedded file, if one installation should hold every language, if the user chooses the language, or if you want a runtime language switch.

Yes, with resource DLLs or an embedded file. See Change the language at runtime and the Multilingual project of the Driving sample.

Yes. The steps are the same; add the -GD linker option to create the DRC file.

Yes. Soluling converts Sisulizer and Multilizer projects, and it imports the translations of existing localized files when you create a project. See migration.

Related

All guides