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.
- Input
- Application or library file (
.exe,.dll,.bpl) and its.drcfile, 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
- How VCL localization works
- Initial language
- Change the language at runtime
- Translate in Soluling Cloud
- Do and don't
- Typical localizability problems
- Troubleshooting
- The Driving sample
- FAQ
Localize a VCL application, step by step
Six steps take the Driving sample from a hard-coded English application to localized files.
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:
-
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. -
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.Formatfrom Soluling's Delphi library. See patterns. -
Create a DRC file. In Delphi, choose Project | Options | Linking and check Output resource string .drc file; in C++Builder, add the
-GDlinker option. The DRC file gives each resource string its name, such asSResultPlural, so translations stay with their strings when the code changes.
zero form for the hours, so "0 hours" is left out. Plural forms are simplified here.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
.dprfile 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.
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.
& marks the hotkey. Soluling keeps it in the translation and checks that hotkeys are not duplicated.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
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
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.
TNtBase.SetResourceDllDir.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.
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.
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;
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
resourcestringfor 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
.exe, .dll, or .bpl. It reads the source code only if you want your resource string comments shown to the translator.-GD linker option to create the DRC file.Related
- VCL localization - the full Desktop documentation
- Delphi localization - resource DLLs, the initial language, and the Delphi library
- Runtime language change - in Delphi and other platforms
- Supported formats - everything else Soluling localizes