S T R U C T O R I Z E R - User Guide
Features > Translator

As you probably know, Structorizer is available in different languages. Before release 3.25, people in charge of realizing these translations had to deal with rapidly growing text files, manually to sort out what strings they had already translated and what new strings were to be cared about and they had even to tweak Structorizer in order to test their work.

The small developer team, however, is only capable to keep about three translations up-to-date: English, German, and Spanish. For the other languages it is lacking time or competence. So users with a good mastery of the concerned concepts and one of the somewhat neglected languages are invited to help keeping the other localizations consistent and up-to-date.

Since release 3.25, Structorizer therefore integrates a component called "Translator". It allows easily to edit the different translation strings and highlights what work has already been done (i.e. all differences w.r.t. the locale delivered with the product version) and which translations are still missing.

Besides this, you may freely switch to another language to check or compare other translations. Last but not least, this maintenance component allows you to test, i.e. to preview your current translation, which makes testing a lot more user-friendly than it had been before.

Translator 3.25

Its usage is pretty straightforward. If you want to contribute to the localization, start the Translator from the Structorizer "File" menu and select the language you are interested in via the button showing the flag of a representative country for the language.

Then you will be presented the translation contents in several chapters selectable by the tabs:

  • Header (representing the language file header with describing comments and change history);
  • Structorizer (translations of the core product);
  • Arranger (translations for GUI of the Arranger component);
  • Executor (translations for the GUI of the Executor component).

Each of the tabs (except the Header tab) shows you a scrollable table of three columns:

  1. Key string (dot-separated hierarchic sequence of component identifiers or numbers, possibly followed by a bracketed condition);
  2. English caption or text (as far as available);
  3. translation in the selected language (as fas as available) - this column is the only editable one.

Highlighting colours:

  • Cyan-coloured rows (as in the screenshot above) having a string enclosed by "-----[" and "]-----" in the first column represent a section name and cannot be edited. They just group entries belonging together.
  • Missing translations in editable rows are highlighted in orange. Note that in certain cases the English translation may also be absent due to missing necessity (e.g. in cases of one-way dialogs or file extension names), as shown in the screenshot above.
  • Translations added or modified w.r.t. the delivered locale are highlighted in green (only in the last column).
  • If a translation was deleted (in comparison to the delivered locale) then the respective entry will be hightlighted in red (only in the last column).

On selecting a row, the background colours vary to emphasize the selection.

Changes are cached but not automatically saved to file. As soon as a language set contains at least one modification, the respective language button will show green background, therefore, to indicate unsaved changes. So it is easy to stay in control and keep track for what languages there are unsaved changes. (With some look & feels, however, this button colouring may hardly be detectable. You may try with a different look and feel then, controlled by the look & feel preference of Structorizer.)

Mind the place holders in the texts. These are meant to be replaced by other texts at run time. There are two kinds of place holders:

  • Ordinary ones, starting with a percent character: "%", "%1", "%2", etc.;
  • Element name place holders, starting with '@' and followed either by a single lower-case letter or an internal element class name, enclosed in braces: "@a", "@b", "@{For}";
  • Indexed placeholders "[#]" to be substituted by the current index for array targets.

If place holders of these kinds appear in an English master text then they should also be put at appropriate positions (according to the grammar requirements) into the respective translation texts. Read more about the element name place holders (introduced with version 3.27-04) in section Preferences => Element names.

You may search for a certain substring on the current locale tab (since version 3.27-04). The "Find" dialog is opened by pressing key combination <Ctrl><F> (as usual):

Translator Find dialog

The use of the Find dialog is quite straightforward: Enter the substring you are looking for, select the column numbers (with regard to the currently shown table) you want to restrict your search to, decide whether the search is to respect letter case or not, and press one of the upwards or downwards buttons (the ones showing a blue triangle). Then the previous or next line containing the given substring wil be leaped to and selected. This should help you preserving translation consistency.

As mentioned above, you may arbitrarily switch to another locale (e.g. for comparison) without losing your changes, simply by pressing the respective language button (or by pressing the <Enter> key while the button has the focus). If you click on the language button of the very locale you are currently working on and there are cached modifactions for this language then you will be asked if you want to discard the changes. If you agree then the original locale will be reloaded. If you decline then nothing will happen (the button action will be cancelled).

On closing the Translator, however, you will be warned if there are unsaved changes for some of the languages. You better save them before or at least now. If you re-open Translator without having closed Structorizer, however, the changes may still be present. Caution: You won't be warned of unsaved Translator changes when you close the owning Structorizer (i.e. the entire application)!

To preview the modifications in the currently running Structorizer, press the "eye" button eye button in the toolbar (also see images above).

In order to save the translations of a language including all cached modifications for it into a file, make sure the respective language is selected (look e.g. at the header of the third table column) and then press the save button - it's the rightmost button of the toolbar, showing the usual floppy disk symbol. (You might have to enlarge the window to access it, cf the image above where only a section of it is visible.) A file selection dialog will pop up and allow you to choose a target folder and - if wanted - a differing file name. If you happened to conduct modifications for several languages then each translation file must be saved separately. After having saved the changes, the associated language button colour will not return to the default button colour (usually some shade of gray) but turn pale green, indicating that all changes will stay cached. This way, you may continue modifying the translations without having to begin from start. Any new modification will turn the button background to bright green again, of course.

You may (re-)load saved translation files for a locale into Translator in order to resume with the result of a previous session. To do so hold the <Shift> button down while you click on the appropriate language button. This will switch to the respective locale and open a file selection dialog allowing you to choose a translation file for the selected language from the file system. The translations found in this file will be loaded into Translator (for the selected language). All differences to the original locale will be highlighted as if they were just edited (see description above). The heading of the last (third) column (in every tab) will show the file path together with the locale name, e.g. "es (/usr/home/mickey/language_files/es1.txt)". If there had been unsaved changes for the selected locale before you clicked the button then Translator will first ask you whether you want to discard them (which is prerequisite for - or side-effect of - loading the file); by declining you cancel the loading action (nothing will happen). So if you'd rather save the changes you should cancle the overloading, save the pending changes and then try to load the file again.

Be aware that Translator does not check whether the loaded file actually belongs to the selected language or not. If not, then nearly all entries are likely to be marked as changes, of course.

Note: Release 3.25 (and some subsequent versions) changed the structure of several keys. Further releases might do so as well. So if you load a file originating from an earlier Structorizer version you may see several regions highlighted in red i.e. as deletions whereas some translations may not be displayed though possibly being present in the file, which is due to the effect that some translations couldn't be associated anymore. If you know what you are doing, a manual modification of the keys in the text file according to the ones shown in Translator may help to avoid losses. (But if it's a lot of added text being eclipsed then you might also send the outdated file to the development team, i.e. bob@fisch.lu, to let us sort it out - we know the mappings, of course.)

Note also that saving a translation file does not mean that your local Structorizer installation would automatically use your modified translations from now on! You may force Structorizer to use a modified language file explicitly, however, by choosing the "empty / user-specific locale icon From file ..." menu item in the language preferences menu: The path of the loaded file would even be kept in the structorizer.ini file and hence automatically reloaded on the next start - until you select another language.

As already stated in the introduction, however, the Translator tool is chiefly meant to facilitate the maintenance and usability improvement of the Structorizer product. So the best you can do is to send an accomplished translation file in after having tested it by the preview tool) as requested under the IMPORTANT note in the header part of each translation file. (Don't forget to add a description of your changes to the Revision list section of the Header chapter.)

Last, but not least, you may create a translation file for a "new" idiom - meaning a language not having been provided so far by the language preferences. To do this, simply press the "?" button in the toolbar instead of one of the flag buttons. This way, you may start a completely new translation from scratch, i.e. with an empty third column. Just fill in the Header chapter appropriately, i.e. specify the language and yourself as author etc., and send the file in after completion. The Structorizer team will be grateful for your help.