Localization and Language Switching in FastReport VCL

In today's world, the ability to provide your software to customers around the globe is of great importance. Therefore, FastReport VCL supports about 40 of the most widely spoken languages for localizing the user interface. 

Starting from version 2023.2, the localization mechanism in FastReport VCL has been significantly improved — it is no longer necessary to recompile in order to translate FastReport into other languages. The localization package is included in all FastReport VCL delivery kits. Localization is performed "on the fly" by selecting the desired language in the Report Designer from the "View — Language" menu. Moreover, you can manage the interface language of FastReport VCL directly from the code!

Checking and Installing Localization Packages 

For localization to work correctly, it is necessary for the IDE to have the localization packages (frxLanguageXXX) and the localization controller package (frLocalization) installed. In the Windows operating system, localization packages are automatically installed for the Delphi and Lazarus IDEs. If the localization menu is not available, you need to check if these packages are installed in the IDE. In Delphi, you will see the following window:

The localization menu in Lazarus looks as follows:  

If any of the translation packages are not required, they can be removed from the development environment.

Working with TfrLocalizationController and Language Selection

As mentioned earlier, changing the language in FastReport within the report designer is very simple. Go to the "View — Languages" menu and choose the desired language.

To connect FastReport localization to the application, you need to use the TfrLocalizationController component. Simply place it on the main form of the application. Next, for Delphi, right-click on the component, and then in the dropdown menu, select the language that you need FastReport to support in your program:

After this, you need to select the language for the TfrLocalizationController component that will be loaded by default when the application starts. You can also add the module containing the necessary localization to the uses section of the main form.

It should be noted that by default, FastReport VCL uses the English language, so if you only need English, there is nothing else to do.

To connect localization in Lazarus, you need to add the language package to the project and then add the module for that language.

Changing Language from Code

In some situations, it may be necessary to manage FastReport VCL localization from the program code. This is done as follows:  

frLocalizationController.Language := ‘German’;

The following code sets the language to German. Do not forget that your program must be compiled with the language package you wish to switch to. You can find out which language packages the program is compiled with using the code below. To do this, you need to include the Types module, place TButton and TMemo components on the form, and write in the Button.OnClick event handler:

procedure TForm1.Button1Click(Sender: TObject);
var D:TStringDynArray;
 I: Integer;
begin
  Memo1.Lines.Add('Default Lang: '+TfrAvailableLanguagesController.GetDefaultLanguageName);
  Memo1.Lines.Add('Current Lng: '+frLocalizationController1.Language);
  Memo1.Lines.Add('Suppotred languages:');
  D:=TfrAvailableLanguagesController.GetLanguages;
  for I:=Low(D) to High(D) do begin
    Memo1.Lines.Add(D[I]);
  End;
end; 

Please note that the English language is not included in the list of supported languages, but it is always available by default.

Editing Localization via the Localizer

You can open the Localization Editor as follows:  

• In the Delphi IDE, go to the menu "Tools… - Localization Editor…"  
• In Lazarus, navigate to the menu "Services - Localization Editor…"

You can invoke the "Localization Editor" from your program using the code below. However, this method is not available in all versions.

  frLocalizationController1.ShowLocalizationEditor;

Purpose of controls in the localization editor:

	open the *.xml file with translation
	save the *.xml file with translation
	save the translation file with a specified name
	undo the last action
	redo the undone action
	set the translation language
	filter records by mask
	clear the filter
	show only translated records
	show only untranslated records

The “Localization Editor” allows you to translate FastReport VCL resources into various languages line by line.

In the center of the editor is a grid with the translatable values.  

The first column displays the identifier of the element that is to be translated. It is always a string, even though some rows may contain numbers, as their string representation is used.

The second column shows the original value of the element in English.

The third column contains the translated value of the element for another language.

Let's move on to the principle of how the localization editor works. Upon loading, the editor checks which localizations are available to the application it is embedded in. It then populates the list of available languages (a combo box for entering the target language). The currently set localization is active for editing. You can choose and edit the translation for any of the available languages and save it to an XML file. If you already have an XML file with translations, you can load it for editing.

In the localization editor, you can switch between display modes. For example, you can show only those elements whose translation matches the original in English, or conversely, show only those elements whose translations differ from the English version. However, it should be noted that not all elements need to be translated.

You can apply a filter to the entries in the grid. A grid element is displayed only if the filter value exists in any column. You can also sort the grid in both ascending and descending alphabetical order by clicking on the header of any column.

If you have modified the translation file, you can connect it to the application instead of the standard one. To do this, you need to include the frResources module in the uses clause using the following code:

  frStringResources.LoadFromFile('mylanguage.xml');

We recommend restarting your application after editing files for the correct display of all translated resources. It should also be taken into account that the loaded translation immediately becomes active but will only work until the first switch of the language. Upon switching back to that same language, the localization will be pulled from the resources connected to the program.

Additionally, you can compile the resource with the translation file yourself. Place it in the directory with the corresponding language module and use it in your program. To have this translation appear in the IDE, run the installer and select the Recompile mode, or simply recompile the package for the language you need. In Lazarus, you will need to rebuild the IDE afterward; in Delphi, you will need to restart the environment.

If you want your translation to be retained after each update, you can send the localization file to us at support@fast-report.com. We will review the received file and add it to the installer.