Soluling home   Document home

How to Localize Delphi FireMonkey Applications

This tutorial shows how to localize your Delphi FireMonkey application using Soluling. You can use this method with VCL projects, too. Soluling reads your Delphi project file, .dproj, and creates a single multilingual resource file, .ntres. The resource file contains the forms and strings in multiple languages. You can either add the file as a resource into your project or deploy it with your application. On runtime, the application gets the translated forms, strings and other resources such as images and audio data from the resource file.

Steps you need to do before your can localize

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

1. Enable resource string translation

Starting from Delphi 10.4 Sydney, RTL has a hook (LoadResStringFunc variable in System unit) to translate resource strings on run time. To enable the hook, add NtResourceString unit into your project.

uses
  NtResourceString;

If you use Delphi 10.3 Rio or earlier, you cannot use the resource strings but you need to use the _T function with strings. See the samples in <data-dir>\Samples\Delphi\FMX\Version1 folder.

2. Internationalize your code

You need to Internationalize your source code strings.

3. Call _T function to translate forms

.ntres file contains the localized form data. To use the localized form call _T fuction in the OnCreate event of each form. If you use the visual form inheritance you only need to call _T fuction in the OnCreate event of the base form.

uses
  FMX.NtTranslator;


procedure TForm1.FormCreate(Sender: TObject);
begin
  _T(Self);
end;

This translates the form into the active language.

4. Turn on DRC file generation in your Delphi project

Delphi's DRC file maps a resource string to the runtime id. This is needed to get a unique and immutable context values for resource strings.To create a DRC file, start Delphi, choose Project | Options | Linking, and check Output resource string .drc file checkbox. If you use Delphi XE or older, select Detailed in the Map file selection.

Now, Delphi generates a DRC file each time you build the project.

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

Create a Soluling project

Start Soluling. Click New from File or Files button in the main view or drag and drop your Delphi project file (.dproj) on the main view. Soluling start the Project Wizard that collects the information needed to create a new Soluling project. The first sheet of the wizard is the Scan method sheet. Select the scan method. If you select the Application or library file method, select the configuration(s) and scan files.

Click Next. The Options sheet appears.

Click Next. The Select Languages sheet appears.

Add the languages you want to localize. Later you can add new languages at any time. Set the original language of your original language. Click Finish to complete the 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.

Build the resource file and add it to into your project

When you build the project, the output file is a single multilingual resource file (NtLangRes.ntres) that contains the form, strings, and other resources in the languages you have in the Soluling project file. You have two choices to use the translation file in your application.

Option 1 - Embedd the resource file into the application file

Add the NtLangRes.ntres resource file as a custom RCDATA resource into your Delphi project. Choose Project | Resources and Images from Delphi.

Make sure the resource identifier is NtLangRes. Add the NtResource unit, call _T function for each form, and compile your project. Now it is multilingual and enabled for the runtime language change. FireMonkey localization can also be used in VCL projects.

Option 2 - Deploy the resource file as a standalone file

Another choice is to use the resource file as a standalone file. Typically you first either deploy or download the file to a directory. Then, in your application code, set the NtResources.ResourcePath property. This must be set before any form gets created. A good place is the initialization section of the main form.

initialization
  NtResources.ResourcePath := '/Documents/Donwloaded/NtLangRes.ntres';
end.

Note! All the platforms (iOS, Android, etc.) of Delphi use the same .ntres file, but the file paths are very platform-specific, so you most likely need to use conditional compiling.

If you don't specify the ResourcePath, Soluling code will try to find the file from directory returned by TPath.GetDocumentsPath (Delphi's RTL code). The directory is platform specific:

<applicationname> is the filename of your application without the extension

In addition to the multilingual resource file (.ntres), Soluling can also create language-specific resource files (.ntlang). You can deploy these files instead of the .ntres file. This makes it possible to add new languages without changing any installed file. To make Soluling create .ntlang files, check either Languages specific resource files or Both in Output file type group box in the Delphi build options sheet.

If you set the ResourcePath property, set only the directory part. for example.

initialization
  NtResources.ResourcePath := '/Documents/Donwloaded';
end.

Soluling code then tries to find all .ntlang file in that directoru and uses them.

Running the application

After you have added the resource file, the application is multilingual and you can run it in any language, any configuration and any platform.

If you change your application such a way that the original resources change (e.g. edit forms or add or change a resource string) you have to create updated resource file. Start Soluling, open your project and choose Home | Build All. This updates the resource file to contain current form structure and strings. You can automate this using SoluMake.