Delphi FireMonkey

Delphi FireMonkey Localization

Localize a Delphi FireMonkey application once for every platform: Soluling reads your Delphi project, lets you translate the forms and resource strings, checks the translations, and builds one multilingual resource file that works on Windows, macOS, iOS, Android, and Linux.

Mobile platforms don't support resource DLLs, so FireMonkey applications carry their translations in a resource file that Soluling's Delphi library reads at runtime. 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 DPR Driving.dproj Soluling 150 60 Driving Time Driving distance: Speed: Round time Calculate Fahrzeit Fahrstrecke: Geschwindigkeit: Ungefähre Uhrzeit Berechnen The form as it is in the project has been translated in the editor You ship RES NtLangRes.ntres fi fi.ntlang de de.ntlang ja ja.ntlang One resource file with every language, or one file for each language You build DPR Driving.dproj Soluling 150 60 Driving Time Driving distance: Speed: Round time Calculate Fahrzeit Fahrstrecke: Geschwindigkeit: Ungefähre Uhrzeit Berechnen The form as it is in the project has been translated in the editor You ship RES NtLangRes.ntres fi fi.ntlang de de.ntlang ja ja.ntlang One resource file with every language, or one file for each language
The same resource file works on every platform: on Windows next to the .exe, and on macOS, iOS, Android, and Linux inside the application package or the documents folder.
Input
Delphi project (.dproj) with its compiled application and .drc file
Output
A multilingual resource file (NtLangRes.ntres) to embed or deploy, or a language file for each language (fi.ntlang)
Runtime
Soluling's Delphi library loads the language and translates the forms with _T; it also changes the language at runtime
Preview
Visual form editor that shows the forms in each language

On this page

Tutorial

Localize a FireMonkey application, step by step

Six steps take the Driving sample from a hard-coded English application to a multilingual one.

01

Prepare: make the application localizable

The original Driving application writes its result like this:

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

Internationalizing the application takes four changes:

  1. Move the strings from code to resource strings. Declare them with resourcestring, and add the NtResourceString unit to the project. It hooks the RTL's resource string loading (Delphi 10.4 Sydney and later), so the resource strings come in the active language.
  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. See patterns.
  3. Translate the forms with _T. Call _T(Self) from FMX.NtTranslator in the OnCreate event of each form. With visual form inheritance, call it only in the base form.
  4. Create a DRC file. Choose Project | Options | Linking and check Output resource string .drc file. It gives each resource string its name, such as SResultPlural.
Moving hard-coded strings to a resource string pattern and translating the form The hard-coded hours and minutes strings stay English and are not plural aware. After internationalizing, the form is translated with _T, and the code formats the SResultPlural resource string, which has English and Finnish plural patterns. Before: Original\Unit1.pas HoursLabel.Text := IntToStr(hours) + ' hours'; MinutesLabel.Text := IntToStr(minutes) + ' minutes'; ✕ Stays English, no plural forms Internationalize After: Localized\Unit1.pas _T(Self); // in FormCreate ... ResultLabel.Text := 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.

Using Delphi 10.3 Rio or older? Resource strings can't be translated at runtime there; wrap the strings in the _T function instead, and choose a source code scan method in step 02. See the Samples\Delphi\FMX\Version1 samples.

02

Add: create a Soluling project

Compile the application in Delphi, then drag and drop the Delphi project file (.dproj) on Soluling. Project Wizard starts.

  • On the Scan method page, keep Application or library file (Delphi 10.4 Sydney and later), and check the configuration and the compiled files to scan. Soluling reads the forms and resource strings from them. The source code methods are for older Delphi versions.
  • On the Options page, keep the default settings.
  • On the Select Languages page, add the target languages, and click Finish.

One project serves every platform: the forms and strings are the same on Windows, macOS, iOS, Android, and Linux, so you translate them only once.

Project Wizard Driving.dproj goes through Project Wizard's Scan method page (application or library file, with the Win32 Release configuration), Options page, and Select Languages page (Finnish, German, Japanese). Drop Driving.dproj Scan method Application or library file ☑ Win32 Release Options Default settings Languages Finnish (fi) German (de) Japanese (ja) The source code scan methods are for Delphi 10.3 Rio and older.
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.

  • 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 Form1 properties with Finnish translations. The selected row, DistanceLabel, is highlighted on the Finnish form in the visual editor. Grid: Form1 Context English Finnish Caption Driving Time Ajoaika File1.Text File Tiedosto DistanceLabel.Text Driving distance: Ajomatka: SpeedLabel.Text Speed: Nopeus: CalculateButton.Text 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
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. See validation.

Validation

⚠ Inconsistent format string Unit1.SResultPlural (German) Original uses one %d in each plural form; the translation uses %1:d: ... {plural, one {%1:d Minute} other {%1:d Minuten}} ⚠ Inconsistent pattern count Unit1.SResultPlural (Japanese) Japanese has only the other plural form, but the translation has one and other.
05

Build: create the resource file

Choose Home | Build All. Soluling writes NtLangRes.ntres, a multilingual resource file with the forms, strings, and other resources in every language of the project. Use it in one of two ways:

  • Embed it. Add NtLangRes.ntres to the Delphi project as an RCDATA resource named NtLangRes (Project | Resources and Images), and compile. The application now contains every language, on every platform.
  • Deploy it as a file. Deploy or download NtLangRes.ntres with the application, and set NtResources.ResourcePath before the first form is created if it is not in the default place. This lets you update translations without recompiling.

On the Delphi build options sheet, you can also create a language file for each language (fi.ntlang, de.ntlang, ...). Deploy the ones you need; adding a language doesn't change any installed file.

Embedded and deployed resource files Embedded: the resource file is compiled into Driving.exe, the .app, or the .apk. Deployed: Driving.exe with NtLangRes.ntres, or with fi.ntlang, de.ntlang, and ja.ntlang, next to it or in the documents folder. Embedded (RCDATA NtLangRes) DIR Win32\Release\ EXE Driving.exe every language inside; also the .app and .apk Deployed DIR Win32\Release\ EXE Driving.exe RES NtLangRes.ntres or the language files: LNG fi.ntlang de.ntlang ja.ntlang
On Windows, the library looks for the file next to the .exe and then in the documents folder; on the other platforms, in the documents folder of the application.
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. Then build again: the resource file must match the current forms and strings. If you embed it, compile the application again too.

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

Reference

One multilingual resource file for every platform

The VCL loads a resource DLL for its language, but iOS and Android don't support resource DLLs, and FireMonkey applications usually ship one package with every language. So Soluling builds the translations into its own resource format. At runtime, Soluling's Delphi library reads the resource file, _T applies the translated form data to each form as it is created, and NtResourceString returns the resource strings in the active language.

FireMonkey on Windows only? You can also localize the compiled application like a VCL application, with localized files or resource DLLs; see the Binary version of the Driving sample and the Delphi VCL guide. The resource file approach of this guide can also be used in VCL applications.

Choose and change the language

The library starts the application in the device's language if the resource file has it, and otherwise in the original language. To start in a specific language, set DefaultLocale (for example, 'fi') in an initialization section, as the sample does. To let the user change the language, register the languages and show the language dialog of FMX.NtLanguageDlg. It loads the selected language and translates the open forms; the procedure you pass sets the texts that the code sets again:

// Unit1.pas in the Localized version of the Driving sample
procedure TForm1.FormCreate(Sender: TObject);
begin
  NtResources.Add('English', 'English', SEnglish, 'en');
  NtResources.Add('Finnish', 'suomi', SFinnish, 'fi');
  NtResources.Add('German', 'Deutsch', SGerman, 'de');
  NtResources.Add('Japanese', '日本語', SJapanese, 'ja');
  _T(Self);
end;

procedure TForm1.Language1Click(Sender: TObject);
begin
  TNtLanguageDialog.Select(procedure
    begin
      CalculateButtonClick(Self);
    end);
end;
Runtime language switch The English Driving Time form, the 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, on every platform

Translate in Soluling Cloud

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

  • Delphi projects. Soluling Cloud can't scan a Delphi project 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, and add NtResourceString.
  • Call _T(Self) in the OnCreate event of every form.
  • Create the DRC file, so the resource strings keep their names.
  • Store whole sentences with placeholders, and use plural patterns for numbers.
  • Use layouts and alignment that leave room for longer text.
  • Build the resource file again whenever the forms or strings change.

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.
  • Ship an old resource file with a new build; the form data must match.
  • Plan on resource DLLs for iOS or Android; they don't support them.

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.
A form is not translated The form stays in the original language Call _T(Self) in its OnCreate event, or in its base form.
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 Use layouts and alignment, or give the controls more room.
No DRC file Resource strings have contexts that change when the code changes Turn on Output resource string .drc file, compile, and scan.

Troubleshooting

Symptom Likely cause What to do
The application stays in English The resource file is not embedded, or the library does not find it Check the RCDATA resource named NtLangRes, or set NtResources.ResourcePath.
Resource strings stay in English NtResourceString is not in the project, or Delphi is older than 10.4 Add the unit; on older Delphi versions, use _T for strings.
Forms show old or mixed texts The resource file was built from an older version of the application Scan and build again, and compile the application again if you embed the file.
Some texts stay in English after a language change The code sets those texts Set them again in the procedure you pass to TNtLanguageDialog.Select.
The file is not found on a mobile device It is not deployed to the documents folder Add it to the deployment of the platform, or embed it.

The Driving sample

The sample is in Samples\Delphi\FMX\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 a resource file and a runtime language switch, for every platform.
  • Binary: localized from the compiled file, like a VCL application, for Windows.

The Samples\Delphi\FMX folder has more samples, for example, images, message dialogs, and the _T function for older Delphi versions. See FireMonkey localization and Delphi localization in the Desktop documentation for all the details.

FAQ

Yes. The resource file works on every FireMonkey platform: Windows, macOS, iOS, Android, and Linux. Embed it, or deploy it to the documents folder of the application.

Yes. See Choose and change the language and the Localized project of the Driving sample.

Embed it if you want one file with every language. Deploy it, or the language files, if you want to update translations or add languages without compiling the application again.

Translating resource strings at runtime needs Delphi 10.4 Sydney or later. With older versions, use the _T function for strings and a source code scan method.

Yes. The resource file and _T work in VCL applications too. Most VCL applications use resource DLLs instead; see the Delphi VCL guide.

Related

All guides