GnuGetText tools for Delphi

Additional tools

This program provides a graphical user interface for the creation and management of multilingual translations. All the functions described here are combined under one roof:

• Scanning of source files to create a new or updated template for the translations
• Merging an existing translation with the updated template
• Editing of the translation using a suitable editor (e.g. PoEdit)
• Optional editing of the ignore lists using a text editor (e.g. Notepad)
• Copying the updated mo files to the subdirectories of the project provided for this purpose
• Optional embedding of the translations into the exe file of the project

The settings, e.g. the name of the text domain or the languages used, are saved separately for each project in a dxgettext.ini file, which is located in the respective project directory. When the project directory is changed, the corresponding settings will be automatically loaded.

Settings

• Project directory: The desired project directory can be selected by clicking the button . Directories that have already been used were saved and can be opened directly by expanding the list (click on the small arrow on the right).

• Selection of the source files to scanned: Either enter a mask of the file types to be scanned, as shown above (e.g. *.pas *.dfm *.dpr for Delphi), or enter a fixed list of files (see screenshot on the right), which can be edited by clicking on one of the two buttons
• Also scan subdirectories: Optionally, the files of the subdirectories of the project directory can also be scanned. It is possible to exclude any combination of subdirectories from the scan. The selection is made by clicking on the button to the right of the input field.
• Text domain: GnuGetText for Delphi offers the possibility to separate translations into different text domains. This makes it possible to translate groups of program components (e.g. units and dialogs used in different applications) separately. The default domain for an application is always called default. The names of other domains are freely selectable (e.g. units), but must be specified in the source text in the same way.
• Location of the mo files of the project: These are usually located in subdirectories of the location of the project's exe file. They must always have the form of the type locale\<LangId>\LC_MESSAGES\ where <LangId> is replaced by the respective abbreviation of the desired language, e.g. de or fr.
  This information is required to specify the destination of the mo files to be copied (see below). You can select whether the destination is only one directory or whether the copy should be made to all existing subdirectories that correspond to the above form, e.g. ..\Projects\Translate\sample\debug\locale\de\LC_MESSAGES\ and ..\Projects\Translate\sample\release\locale\de\LC_MESSAGES\.
  In the first case, the directory with the exe files must be selected; in the second, any directory above it must be selected. The function Embedding the translations in exe files is only available in the first case.
• Language settings:
  • List of supported languages: All languages that are to be supported in the project, must first be added to a list (see figure above). To do this, select from from the drop-down list on the right-hand side and click on Add to list.
  • Translations subdirectory: The subdirectory (languages in the example) within the project directory in which the translated po files are located is specified here. A subdirectory of the form <Language Id> must exist there for each language, e.g. de or fr (see screenshot on the right).
  • Selection of Languages: Before starting one of the actions described below, e.g. merging a translation with an updated template, all languages to which the action is to be applied must be selected. To help, there are two buttons with which all languages can be selected or deselected. Otherwise, you can use the familiar Windows method of clicking on the entries while holding down the Shift or Ctrl key. Two further buttons can be used to change the order in the list. After clicking on the button with the magnifying glass, statistics for the selected translation are displayed (see also here). For a better overview, incomplete translations are highlighted in color in the list.
  • Available languages:
    The list of available languages included with the program package contains all common European languages as well as Chinese. It can be extended by the user as required in order to make other languages available for editing. To do this, open the languages.en or languages.de file, which is located in the lang subdirectory of the installed program, with a text editor and insert the desired language in the form <shortcut> - <name>as a new line. The abbreviation consists of two letters and corresponds to those specified by Microsoft, e.g. ja - Japanese.

• Settings for processing:
  • Encoding of source files: This setting should normally remain on the default US-ASCII. If the source texts contain characters from other character sets, e.g. if German was used as the source language, the encoding selection must be changed accordingly.
  • Add likely ignores to ignore.po file: After scanning the source texts, the list of strings is checked for expressions that are obviously not text specified by the user, e.g. a font name or a number string. These are then saved in the ignore.po file. The user can also add further entries to this text file himself.
    In addition, the user can provide his own list that specifies certain patterns used for naming the components. Matching entries are then automatically moved to ignore.po. This list has the name IgnoreObjects.txt and is located in the base directory of the project (see above). A sample list is included in the program package. If desired, it can be customized by the user.
    Example: bb_=bit button recognizes all entries (msgid) that begin with bb_. They are indicated by the comment # Seems like unrenamed bit button.
  • Remove items from text domain present in ignore.po file: All entries found in the ignore.po file will be automatically removed from the template and are therefore no longer part of the translation.
  • Edit translation immediately after merging: If this option is selected, the editor (e.g. PoEdit) will be started immediately after merging.

• Settings for merging:
  • Accept similar strings and mark as Fuzzy: When merging, an exact match of the original texts (msgid) is normally checked. If this is not the case and this option is activated, the system also checks whether there are similarities to another original text. An algorithm is used for this to check for phonetic similarities (SoundEx from the Delphi system library). This translation, which is recognized as similar, is then accepted but marked for further editing (Fuzzy).
  • Language-dependent settings: The following settings can be made separately for each language.
    • Retain automatic comments: When creating the template, automatic comments are inserted that make it easier for the program developer to find the position of the respective string in the source code. If this option is selected, these are transferred to the translation file.
    • Retain obsolete translations: Translated strings that are no longer used in the current template can optionally be added as comments with the #~ marker.

• Settings for saving:
  • Sort entries by original strings (msgid): The po file created can either be saved in the order of the template or sorted alphabetically according to the original strings (msgid).
  • Overwrite template file: An existing template will be overwritten during the update without prompting.
  • Create backup file of old translation: A previous version of the translated po file is always retained (e.g.as default.~po). This setting can be made individually for each language.

Actions

Clicking on one of the large buttons at the bottom right will start one of the following actions:

• Create template from project sources: In the program window (see figure above), the log of the progress of scanning for strings to be translated in the source texts is displayed on the left. Special attention should be paid to whether errors are displayed, e.g. if non-ASCII encoded characters are used in the source texts. In this case, you must either change these characters or select a different text encoding (see above).
  The template is always output in UTF-8 format.
• Merge translation with template: All translations of the selected languages are merged with the updated template. The progress is displayed on the left in the log window.
• Edit translation: Clicking this button will open the the file with the translation into the selected language with the editor (z.B. PoEdit).
• Edit ignores: Click on this button to open the default.po file (or the po file specified under Text domain) and ignore.po with the system's standard text editor. String entries that are not to be translated can thus be moved to the ignore file. The template must then be updated.
• Copy mo file to binary folder of project: Copying the updated mo files to the directories locale\<language ID>\LC_MESSAGES\ (see above) is started. The program automatically checks whether these are up-to-date. If not, the po file is converted to the corresponding mo file before copying (see also).
• Embed translations in executables: This function is only available if a single directory is selected as the target for the mo files. The translations are automatically embedded in all exe files found there. The languages and text domains to be used can be selected individually in a dialog (more information).
• Copy the action log to the clipboard: Clicking this button copies the entire displayed log to the Windows clipboard.

Sometimes it is necessary to compare translations, e.g. when a revised version is available, or to transfer translations from one project to another. PoCompare loads two translated po files, the one to be edited and the one to be used for comparison, and searches for all entries where the original text (msgid) is the same and the translation (msgstr) is different. The number of entries found is displayed at the top, with a selected entry below:

• ID: Original string (msgid) and line numbers of entries in the po files
• Translation - left side: The translated string in the po file to edited
• Translation - right side: The translated string in the po file used for comparison

Selection of the po files to used:
		First select the po file to be edited by clicking on this button at the top left. Then select the po file to be used for comparison by clicking on the button at the top right.
		To find the comparison file more quickly, the search can be started directly in the directory of the po file to be edited by clicking on this button.

These buttons can be used to navigate through the entries found:
		One entry forwards or backwards
		10 entries forwards or backwards
		Go to the first or last entry

These buttons are used for editing:
		The text of the selected entry is copied from right to left, i.e. the translation on the left is replaced by the one on the right. Entries changed in this way are highlighted in color.
		All entries are copied from right to left.
		It is also possible to make changes manually in the left-hand translation window. These must then be confirmed by clicking on the OK button.
		This can be used to undo the last change.
		Clicking this button will save the changes to the left po file.

Further functions:
		Edit the drop-down list of po files to be edited
		Reload both po files
		Open the po file to be edited with the associated editor (e.g. PoEdit)

Command line

Sometimes you need translations for a new project that are already available for another project. With PoImport, these can be transferred quickly and easily. First, the two po files are loaded, the new one to be edited (Po-1) and the one already available in translated form (Po-2). The program checks for all entries in Po-1 whether

1. there is no translation yet, i.e. msgstr is empty,
2. a suitable entry exists in Po-2 (identical msgid).

If this is the case, the translation msgstr is copied from Po-2 to Po-1. The updated po file (Po-1) is then saved.
If necessary, i.e. if there are more untranslated strings in Po-1, you can repeat the import with other po files to complete the translation.

If there is already a translation into a language other than English for a Delphi unit, the resource strings used there (strings defined in the resourcestring section) can be transferred to a po file. To identify the strings, their constant name, e.g. SFileNotFound from the System.SysConst.pas unit, is used. In the po template, this is marked by dxgettext or GgtTranslate as a comment with the note Programmer's name for it:.

This program can be used to create a unit with the translated strings from a Delphi unit (dfm and pas file) in the base language (e.g. English). The translations are extracted from an already translated po file.

In the overview, all strings (msgid) found in the Delphi unit and in the po file are displayed in a list. The origin of the respective string can be seen in the middle column: D = form (dfm file) and P = source text (pas file). To the right is the translation found in the po file. All strings for which a translation was found are automatically marked (check mark on the left-hand side). If necessary, the user can adjust this selection manually. After clicking on the Replace strings button, the translations of the marked strings are inserted into the two files of the Delphi unit. In addition, the unit GnuGetText (if specified) is replaced by the dummy unit GgtDummy in the uses statement. This means that any functions _(..), dgettext(..) and TranslateComponent(..) used in the source text can remain unchanged. The Delphi unit files changed in this way are then stored in a subdirectory of the original with the abbreviation of the respective language as the name.

This program can be used to check a po file for spelling errors. It uses the dictionaries from the Hunspell project, which are also used in many other applications such as LibreOffice, OpenOffice and Firefox. The German dictionary is already included in the installation package. However, any other dictionary can also be selected. There is also a private dictionary for the user, in which he collects all expressions that are not included in the global dictionary but are recognized as correctly spelled

Procedure

After selecting a po file, the program automatically searches for the first suspected spelling error in a translation (msgstr) and displays it in the middle window. Below this, the supposedly misspelled word is highlighted. You now have various options:

1. Add to dictionary ...: The displayed word is added to the private dictionary so that it is recognized as correct in future checks. The next word is then searched for.
2. Replace word: First correct the word manually or click on the ↓ arrow to select the correct word from a list of possible suggestions. Then click on this button to replace the word and then on Next word.
3. Next word: The supposedly incorrect text is ignored and the next word is searched for.

Finally, click on the Save button on the right to save the changes.

Command line

The header of the po file with information on the project, the author, the translator will be displayed, as well as the statistics of the entries..

Command line

If a translator has difficulties understanding the English texts, this program can be used to insert the existing translation into another language as a comment in the new translation. In PoEdit, these comments are displayed in addition to the original English texts in the bottom right-hand field as a note and help the translator to better understand the text.

A widely used application for creating installation archives is the freeware program Inno Setup. It offers the option of integrating the information texts required for the user interface during installation in various languages. The programs offered here can be used to create the required text files with the translations via PoEdit.

Processing takes place in the following steps:

1. The IssToPas program is used to extract the texts of the [CustomMessages] section in the InnoSetup script and convert these as resource strings into a Delphi unit (Pascal).
2. A po template and the corresponding translated po file are created from the unit generated in this way using GgtTanslate or dxgettext and ggmerge.
3. The PoToIss program is used to create a text file in a format that can be integrated into the InnoSetup script.

Extracts the texts of the [CustomMessages] section in the InnoSetup script and converts them as resource strings into a Pascal unit. The following example shows the texts in the setup script on the left and the Delphi unit generated from them on the right:

 
    
    
  [CustomMessages]     
  en.ProgName=Personal Backup %1 (%2-bit)
  en.eventicon=Add messages to event log
  en.Context=Context menus:
  ...
    

    
  unit InstallStrings;
  interface
  resourcestring
    ProgName = 'Personal Backup %1 (%2-bit)';
    eventicon = 'Add messages to event log';
    Context = 'Context menus:';
    ...
  implementation
  end.
    

Examples:
  isstopas.exe E:\Sample\test.iss
  isstopas.exe E:\Sample\test.iss /pref:de /out:testde

Converts the translated texts from a po file into the format that can be integrated into an InnoSetup script.

When the program package is installed, the necessary registry entries are automatically made to adapt the Windows context menus. In addition to the basic functions already described, there are extended context menus for the additional functions listed above:

3. Right-click on a po file, e.g. default.po		2. Right-click on an iss file, e.g. GgtTranslate.iss
opens the selected po file with the respective tool (see the descriptions above).		extracts the texts of the [CustomMessages] section (see above under IssToPas).