GAMBAS BOOK 3.19.1

Since the Online Gamba Book is only available in German, the projects for the individual chapters have been developed in English (standard) with German translation for the past two years. In this way, readers receive projects that can be used in German in Germany. However, all other readers use the project in the English version, since no further translations are made.

When you create a new project, you can specify whether the project can be translated. After a new project has been created, go to the menu Project > Properties > Options. There you can check whether the heading' Translation' contains “Yes”, so that the project can be translated. Select the default language' English'. For the English language, we recommend the localization “English (general)”. This has the advantage mentioned above that whenever there is no language file for the current locale parameters (Locale), the program always falls back to the default language English, so that readers from other countries can at least test the projects enclosed with the chapters in the English version.

After changing the project properties, a new button with a small blue flag appears in the toolbar of the IDE, which opens the project translation (dialog). With CTRL+T you can call up the project translation directly. Then you will see in the' Project translation' window in the combo box next to the blue flag as a symbol for a menu button only the entry (default) and to the right of the green arrow the entry' Deutsch (Deutschland)' in the combo box. This may irritate you at the beginning - but it is correct, because the default language entered in the project properties is English and will not be highlighted! The entry 'German (Germany)' appears because in the case of the author, the locale parameters are set for Germany. Later, you can use the' New' entry in the menu button to create further translations and modify existing ones.

For example, if a translatable Gambas program starts with the default language English, the interpreter explores the current locale. If a translation exists for the current locale in a language file, it is loaded. For example, the translation for the German version of a Gambas project is located in the language file de. po in the (hidden) project folder. lang. Here you can see an excerpt from a language file de.po, from which you can see the file name, the line number as well as the original English character string and its German translation. Note that the last string “Spine (Carbon):” has not been translated:

...
#: FMain.class:11
msgid "Spine Value Calculator for Arrows"
msgstr "Spinewert-Berechnungen für Pfeile"

#: FMain.form:88
msgid "Spine (Wood):"
msgstr "Spine (Holz)"

#: FMain.form:104
msgid "Spine (Carbon):"
msgstr "-"

Otherwise, the standard translation specified in the above options will be loaded. This is indicated by the fact that the English strings are always displayed as long as you have not translated them. This also means that you can carry out the translation step-by-step. Note that changing the original (english) strings always requires a new translation, because it was automatically deleted! The translations are automatically saved when you close the project translation.

All texts displayed on the graphical user interface (GUI) are automatically marked as text to be translated in the project translation. In the program source code, you must place translatable strings in parentheses to mark them as text to be translated. Only then are they recognized by the project translation and a translation is requested in dialog. You always have to think about whether it is useful and necessary to translate a string.

Case 1

blSpineCarbon.Text = "Spine (Carbon):"    
blSpineCarbon.Text = ("Spine (Carbon):")

In this case, both spellings are possible because the text does not necessarily need to be translated. Nothing has to be translated for the first line, the string does not appear in the project translation. A hyphen - the string “-” is entered as the translation for the second line. This means that the string “Spine (Carbon):” has been considered as the text to be translated, but no translation is required or not translated - the original string “Spine (Carbon):” is displayed.

Case 2

' FMain.Caption = "Spine Value Calculator for Arrows"
  FMain.Caption = ("Spine Value Calculator for Arrows") 

The complete string “Spine Value Calculator for Arrows” is marked by the two parentheses as 'to be translated'.

Case 3

' Message.Error("The value for the tensile weight is missing!")
  Message.Error(("The value for the tensile weight is missing!"))

The complete string “The value for the tensile weight is missing!” as argument of the method Message() must be translated.

Case 4

The following line specifies a filter

Dialog.Filter = ["*.png;*.jpg", "Image files"]

Dialog.Filter = ["*.png;*.jpg", ("Image files")]

Case 5

Caution should always be exercised if, among other things, variables - for example sVerb=“reads” - are concatenated into strings and the different grammar of the languages is to be taken into account:

Message("Do you know if she " & sVerb & " a book?")  ' ***

This set contains translatable strings and a (string) variable whose value must also be translated. However, it is not easily translated into German because the sentence structures in English and German are different in this case. While in the German language the verb is put at the end of the sentence:' Do you know if she reads a book?' it would be' Do you know if she reads a book'. Message (“Do you know if she ” & sVerb & “ a book?”) would have to be Message(“Do you know if they become a book ” & sVerb & “?”) after a translation.

sVerb = ("reads")
Message.Title = "TEST"
Message(("Do you know if she") & " " & Tr(sVerb) & " " & ("a book?"))

The changes concern the insertion of blanks (option) in (3*), which would not be visible in the translations if they are at the end or leading blanks and are therefore often forgotten.

To see the text of this message in English, you have to insert an environment variable with variable = LANG and value = en_GB. utf8 temporarily in the project properties under' Environment'.

Figure 11.4.2.1: Original

To see the translation, you must delete the environment variable.

Figure 11.4.2.2: Ratio 1

As a translator, you will be asked for this unsatisfactory result for a simple sentence and you will be asked how the author will come to his senses! The solution is to use the Subst () function. With the following source code section

  sVerb = ("reads")
  Message.Title = "TEST"
  Message(Subst(("Do you know if she &1 &2?"), Tr(sVerb), ("a book")))

and the translation into the German language

Weißt du, ob sie &2 &1?

results in a convincing translation:

Figure 11.4.2.3: Translation 2

The rule should be the rule: Do not concatenate translatable strings with &, but always use the Subst () function. The Tr () function would not be necessary, but the text reads better, because Tr (sVerb) means that the translation (Tr stands for translation) of the verb has to be inserted. The use of Subst () allows you to move placeholders such as &1 &2 and text to any position, thus adjusting the sentence structure of the target language.

The following two examples demonstrate how to structure the texts in order to present a good translation and show a different approach in order to reduce the effort for larger projects:

iNew = 1
bSuccess = False
Message.Title = "Information"
Message(Subst(("You have &1 new message&2!"), iNew, IIf(iNew = 1, "", ("s"))))
Message.Title = "Information"
Message(Subst(("The operation was &1successful."), IIf(bSuccess, "", ("un"))))

These are the translations:

You have &1 new message&2! → Sie haben &1 neue Nachricht&2!
The operation was &1successful. → Die Operation war &1erfolgreich.
s → en
un → nicht (mit nachfolgendem Leerzeichen!)

You need to think about how to write universally translatable text with parameters or how to create structured, less natural text:

Message(Subst(("Number of new messages: &1"), iNew))
Message(Subst(("Status of the operation: &1"), IIf(bSuccess, ("successful"), ("unsuccessful"))))

Case 6

Cases 6 and 7 also use the Subst () function. The first lines declared as comments contain the native form, which is not incorrect.

' txbTensileWeight.Tooltip = ("Range:") & " 10·lbs ≤ " & ("Tensile weight") & " ≤ 100·lbs" ' nativ
  txbTensileWeight.Tooltip = Subst("&1 10·lbs ≤ &2 ≤ 100·lbs", ("Range:"), ("Tensile weight"))

Case 7

' Message.Warning(Str($iTensileWeight) & " " & "is an illegal draw weight value!") ' nativ
  Message.Warning(Subst("&1 &2", Str($iTensileWeight), ("is an illegal draw weight value!")))

Case 8

There are special points you should pay attention to when trying to translate into languages that write from right to left? http://gambaswiki.org/wiki/howto/translate. However, no experience has yet been gained in this case.

The answer to the question: Is it possible to rewrite existing projects with the standard language English (U. S. A.) - this is the standard when creating a new Gambas project - to an English version? is interesting for all those who will need a translation later on. Suppose you have a project with all relevant texts in German and you want the standard language to remain English, but there will be a German translation. You first proceed as for a new project and switch the project to' translatable' in the options and select English as the default language with the localization “English (general)”. Afterwards, you must manually rewrite all German texts on the controls and in the source text to English and then enter the German translation in the translation dialog. The effort is considerable!

A recommendation can be considered: If possible, develop your projects with English texts on the controls and in the source code. Only then can translations in German or other languages be added easily at any time. This ensures that an English version is presented to all users in English-speaking countries or in countries for which you have not translated, and an English version is translated for all other countries.

In the project translation there is the tab 'Import'. After activating it, a file-open dialog opens in which you can select a language file *.po for import into the current project. You can check certain preferences first, if necessary.

The export of a language file is done via the 'Translation' tab in the menu of the menu button with the entry 'Export', followed by three submenus. After the selection follows a file save dialog for the appropriate language file. The suggested filename should be adopted and follows the syntax:

project_name_language_abbreviation_of_the_translated_language_project_version.po (example: spine-de-0.1.7.po).

If you have tooltips for selected controls, they should also be translated. It is advantageous to define the text for the tooltips not in the object inspector, but directly in the source code, because they do not get out of focus. In chapter 20.1.3 Message and I18N → http://www.gambas-buch.de/dw/doku.php?id=k20:k20.1:k20.1.3:start you will find hints that translations in a project can also have an effect on the (required) width of control elements and must therefore be considered under the aspect of form layout.

To start the Gambas IDE for tests temporarily in the English version, you have to set the appropriate environment variable' LANG' in a console like this:

$ LANG=en_GB.utf8 gambas3

In order to put the hints in this chapter into practice at least once, you could translate an existing small project (SpineI18NE) into German in English language (standard). The project archive can be found in the download area. The answer to the question of why a project with the standard language German is not translated into English - which sounds more logical - can be found in the first part of the chapter and in sub-chapter 11.4.3.

Select the default language English with the localization “English (general)” and mark the strings to be translated on the controls and in the source code. Translate the project (step by step).

The following translations can be used:

"TextBox" → "-"
"Test input in a TextBox and ComboBox for given input alphabets." → "Test von Eingaben in einer TextBox und in einer ComboBox für vorgegebene Eingabe-Aphabete."
"Spine Value Calculator for Arrows" → "Spinewert-Berechnungen für Pfeile"
"Range:" → "Wertebereich"
"Tensile weight" → "Zuggewicht"
"The value for the tensile weight is missing!" → "Es fehlt der Wert für das Zug-Gewicht!"
"Input error in the TextBox" → "Eingabe-Fehler in der Textbox"
"is an illegal draw weight value!" → "ist ein unzulässiger Zugwert!"
"Calculate" → "Berechnen"
"Reset" → "-"
"Tensile Weight:" → "Zug-Gewicht:"
"lbs" → "-"
"String class:" → "Sehnen-Klasse:"
"Number" → "Anzahl"
"With Quiver" → "Mit Köcher"
"Without Quiver" → "Ohne Köcher"
"Spine (Wood):" → "Spine (Holz)"
"Spine (Carbon):" → "-"
"(AMO)" → "-"

Figure 11.4.6.1: Project translation

The project SpineI18NED with the translation can also be found as a project archive in the download area.