mistake.ws

Lingus help

Introduction

This is not a real manual, it's more like a crash course to get started using Lingus. This document contains information about how to translate your application. If any questions are left open, I am available for questions by mail or by using the forum.

Content

Prepare project

At first the delphi-project has to be prepared for Lingus. To do this the following steps are necessary.

  • Open the project you want to translate with delphi.
  • Make the file LanguageObjects.pas (from LingusDirectory\pas) accessible for your project - either add the file to your project (not good) oder add the file to the search path (good).
  • Units that need to access the translations later need LanguageObjects in their uses clause.
  • Properties of objects (at the moment Caption and Hint) will be processed by Lingus, strings need to be edited in the code. For example 'Hello World' becomes _('Hello World'), similar to gettext. The string '-' is exceptional and will be ignored by Lingus.
  • You need to add Language.Translate(Self); to the Create event or the constructor of your forms, so that translations will be applied to the component of your form. There is also an overloaded version of the procedure available where you can specify procedures that get executed before and after translating using the arguments PreTranslate and PostTranslate. If no language has been assigned to the Language-object as described under Misc, the language to use will be automatically determined. If the current per-user windows language is found in the translations, that one will be used. If not, english will be used. If english is not available, the first found language from the Lingus-translations will be used.

Translate project

After preparing the project Lingus can be used to translate the texts.

  • Start Lingus and create a new project using "File" -> "New...".
  • Configure the new project and import the prepared delphi project in the next step.
  • Text can now be translated - in the left view, a list of found strings from the program is available, in the right view you can edit the translations.
  • Save the project after translating the strings - in this tutorial ProjectDirectory\res\language.lpf. is used.
  • If "Export resource file on save" has not been disabled in the settings, the file ProjektOrdner\res\language.res was written on save, which now need to be added to the delphi project.
  • Open the project file of the delphi project (.dpr) and add {$R res\language.res} after the line {$R *.res}, so the translations will be available to the program at runtime without using external files.

Synchronize translations after changes to the sourcecode

After changing texts of components or strings in your sourcecode, the lingus project should be synchronized with the changed sources.

  • Start Lingus and open the .lpf file belonging to the delphi project.
  • Select "Project -> Synchronize with sources..." from the Lingus menu.
  • Select project folder and import the changed sources.
  • Changes can now be managed very easy. If a new string was found or a string from the Lingus project does not exist in the sources anymore, this will be indicated with an icon. The synchronization dialog provides options to add new found strings to the project, to delete not found strings, or to assign a string from the delphi project that has not been found in the lingus project because it changed to an already translated string.

Misc

  • Change language at runtime

    To change the applications language, the in the initialization clause created LanguageList from LanguageObjects.pas needs to be used to set the property CurrentLanguage of the Language object, as shown in the following example.
    The following call of Language.Translate(Self); is important in all open forms to apply the changes.

    for i := 0 to LanguageList.Count - 1 do
  if LanguageList[i].Available then
  begin
    if LanguageList[i].ID = 'en' then
    begin
      Language.CurrentLanguage := LanguageList[i];
      Break;
    end;
  end;
Language.Translate(Self);

    All objects in LanguageList are from the class TLanguage. They have the property ID, Name and Available. ID is the abbreviation of the language, for example "en" or "de". Name is the language's name. Available tells if the language is contained in the currently loaded project.

  • Load translations from file

    To load translations from a .lpf file, you need to use Language.LoadFromFile('Dir\File.lpf'). This should happen before calling Language.Translate(), because otherwise switching the active language of your application will not work if the loaded translations differ from the translations that are embedded as resource in your application.

  • Icons for languages

    The file LanguageIcons.pas (from LingusDirectory\pas) contains the class TLanguageIcons. If an instance of this class is created, it provides access to the symbols of the different languages. To achieve this the line {$R res\lang_icons.res} needs to be added to the .dpr file of the delphi project after it was copied from LingusDirectory\res\ to ProjectDirectory\res\. At the moment there are only icons for German, English and French included. The property List of TLanguageIcons is an ImageList that contains the language's icons. The index in this list for a specific language can be retrieved by using GetIconIndex(). To get the index to the language German, you need to use IconList.GetIconIndex('de'). Another function is CreateIcon() that returns a TIcon for a specific language. This icon has to be freed by the caller afterwards.