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

The Translator is chiefly a tool to facilitate the maintenance of the application itself but also offers customisation opportunities.

As you probably know, Structorizer is available in different languages. The small developer team alone, however, is only capable to keep about three translations up-to-date: English, German, and Spanish.

So users with a good understanding of the concerned concepts and mastering one (ore more) of the likewise neglected languages are invited to help keeping the other localizations consistent and up-to-date. Even small steps improving the translations are welcome. We promise: You will not be held responsible for missing translations or misspellings or whatever. They will simply be corrected the next time.

To facilitate user's contribution, Structorizer 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 withot forcing you to accomplish a translation during a single session. It may be a lot of work, we know that. But think of the benefits of a good localization.

You may freely switch to another language to check or compare other translations (e.g. in order to disambiguate or to help your understanding). 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);
  • Elements (optional localization of the element type names, also see Element Names Preferences);
  • Keywords (optional localization of Parser Preferences).

Each of the tabs (except the Header tab) shows you a scrollable table of three text 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.

By double-clicking the cell in the the third column, you may edit its content. In some cases the messages may be very long, such that editing within the table cell gets utterly cumbersome. Since verson 3.29-11, there is a fourth column with a button at the end of each editable row to address this problem: The respective button will open a specific translator row editor that offers more comfort. It is described further below.

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. This does not mean, however, that a localization is not necessary. If you don't have an idea what text it should contain then just contact the developer team, please.
  • 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. Note that the translator row editor (as introduced with version 3.29-11) allows you a preview of the element name placeholder substitution.

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.

Translator Row Editor (from version 3.29-11 on)

The editor buttons in the last column

The button in the last table column (see screenshot above) opens a translation editor for the selected table row, showing the key (and possible conditions presented in a table for better readability), a text area with the English default text (from the second column), a text area with the translated text for the currently selected locale, and a third text area where the respective text of a selectable comparison locale can be presented.

Translator Row Editor (initial view)

The checkox "Wrap Lines" allows you to switch between symbolic newlines (escape character sequence "\n") and real newlines:

Translator Row Editor (initial view)

Via the pulldown choice element "?" between the second and the third text area you may select a third language for a reference translation:

Translator Row Editor with comparison language

If you activate the row editor for a line with conditioned key then the conditions will be presented in a table at top:

Translator Row Editor with condition table

The "Elements" button pops up a window, which is listing the available element type name placeholders in short and long form as well as the corresponding translations in the default locale (English), your selected locale, and the most recent comparison locale (so you will not have to leave the row editor in order to look up the placeholders in the header tab):

Translator element placeholder table

By means of the "Preview" toggle button you may have the element type name placeholders in the currently presented texts replaced by the respective element name localizations until you press it again (deselect it). During preview mode, editing is not possible:

Translator Row Editor (with placeholders)

Translator Row Editor (with substituted placeholders)

Undo/redo stacks haven't been implemented in the text area, but you may undo all current changes without leaving the dialog by pressing the "Reset" button. The same effect ist achieved by pressing the "Cancel" button but that it closes the dialog. Eventually, the "OK" button will commit your changes, copy the resulting translation into the related table row and close the dialog.