Skip to main content
Table of Contents

Getting started with the Localizer

This page covers the shortest path to a running TTMSFNCLocalizationLocalizer: what to install, how to add the component, and a minimal snippet that localizes the application on startup. For the full task documentation — switching languages, start modes, persistence, and translation files — see the user guide.

Prerequisites

  • TMS FNC Core installed and the runtime package added to the project.
  • TMS FNC Localization installed.
  • Translations produced with the Localization Editor: the project's translations.json, or separate language files exported from it.

Add the component

The localizer is usually placed on a data module together with the String Catalog and Collector, so a single translation setup is shared by every form in the application. Drop a TTMSFNCLocalizationLocalizer from the TMS FNC Localization palette tab, or create it in code.

The snippet below points the localizer at a folder of translation files and applies the language the user selected on a previous run:

Configure the localizer and apply the saved languagePascalC++
procedure TDataModule1.DataModuleCreate(Sender: TObject);
begin
  { Localizer, Collector and StringCatalog are dropped on this data module at design time. }
  Localizer.LocalizationFolder := TPath.Combine(TPath.GetDocumentsPath, 'Translations');
  Localizer.LocalizationStartMode := lsmManual;
  Localizer.PersistLanguageSelection := True;

  { The localizer already read the folder set in the Object Inspector when the
    data module loaded. The folder changed in code, so read it again. }
  Localizer.RescanLanguages;

  { Apply the language the user selected on the previous run
    (falls back to the source language when nothing was persisted). }
  Localizer.PerformLocalization;
end;

void __fastcall TDataModule1::DataModuleCreate(TObject *Sender)
{
  // Localizer, Collector and StringCatalog are dropped on this data module at design time.
  Localizer->LocalizationFolder = System::Ioutils::TPath::Combine(System::Ioutils::TPath::GetDocumentsPath(), "Translations");
  Localizer->LocalizationStartMode = TTMSFNCLocalizationStartMode::lsmManual;
  Localizer->PersistLanguageSelection = true;

  // The localizer already read the folder set in the Object Inspector when the
  // data module loaded. The folder changed in code, so read it again.
  Localizer->RescanLanguages();

  // Apply the language the user selected on the previous run
  // (falls back to the source language when nothing was persisted).
  Localizer->PerformLocalization();
}

The localizer reads its folder when the data module loads, before OnCreate runs, so a folder assigned in code needs the RescanLanguages call shown above. Setting LocalizationFolder in the Object Inspector avoids it. When you run the application from the IDE on Windows, the localizer reads the project folder instead; see Running from the IDE.

PerformLocalization applies the persisted language (or the source language when nothing was persisted). To activate a specific language instead, call TrySetLocale — see Switching the application language.

Run the application

Compile and run. With LocalizationStartMode set to lsmManual the application stays in its source language until you call PerformLocalization or TrySetLocale; switch to lsmAutoHook to localize automatically as forms are created. Add a Localization ComboBox to let the user change languages at runtime.

See also