Package e4s.translate

Mechanism for localization services (translation of the user interface).

See:
Description

Interface Summary

E4Label_Intf

Interface for Strings (used as labels etc..) with a requirement for translations.

Class Summary

E4ExternalTranslation	Embedd some external translation tool.
E4Label	Basic translation object.
E4LabelApp	Translation object used for application functionality.
E4LabelData	Translation object used for data translation items.
E4LabelNone	Dummy translation object, causes no translation
E4LabelsVec	A Vector that contains labels.
E4LabelSys	Translation object used for core system functionality only.
E4TranslationsClientRepository
E4TranslationsRepository	Repository for the translations.
E4TranslationsVec	Encapsulated Vector class used only to hold elements of type E4Label_Intf.

Package e4s.translate Description

Mechanism for localization services (translation of the user interface).

The concept of localized (human language translated) program code
How to involke translations
Different types of translations
Parameters in translations
Integration of external translation services
How to turn on translation editing

The concept of localized (human language translated) program code works as follows:

1. When creating an application, choose any language as your desired application language. This language mus be defined explicit in e4s.application.Language, for example you could choose english or german as your programming tongue.

2. Write your program code, when you use labels or text strings that are intended to be translated, such as labels for input fields or menuitems, then make use of the programming tongue above. The e4s will automatically treat those Strings as e4s.translate.LabelApp elements. In some cases you require explicit definition of translations, use

LabelApp translation = new LabelApp("Hello World");

If your intend to print out a text, do not use the e4s.html.HtmlContentElement.print(String) function, instead use e4s.html.HtmlContentElement.translate(String).

In some cases, where you don't need translation for certain text elements, you can avoid this by using the e4s.translate.LabelNone class when e.g. assigning a label to some input field.

3. Run your application, choose the user language and test it. Everytime a new translation will be required at runtime, it will be inserted into database table e4s.systabledef.T_D2S_TRANS_APP_Sel.

4.1. You also could turn on translation editing. This means, that at runtime for each e4s.html.HTML element downwards to all nested elements of that page, translations will be collected in an internally used Vector (e4s.translate.e4sTranslationsVec) and when you click the editing symbol an interactive window will be shown enabling you to edit translations only used in this FRAME or HTML context:

4.2. In the application menu, choose the menu item "Translations" and you can edit translations in the database table e4s.systabledef.T_D2S_TRANS_APP_Sel directly.

5. When a user runs your program in another language (e4s.application.Language), then translations will be taken out of the database table e4s.systabledef.T_D2S_TRANS_APP_Sel and displayed, if no translations is defined for a particular text then the original text will be displayed enclosed in [ ] to indicate that a translation is missing.

Step 1 to 2: required to be done by the application developer (programmer)
Step 3 to 5: can be done by some testing staff

Different types of translations:

Whenever an element of interface e4s.translate.Label_Intf is required, you can use one of:

e4s.translate.LabelNone	When no translations is required, that means that the source and translation strings shall be equals
e4s.translate.LabelApp	In application development. Recommended	When translations are requred, that means that source and translation strings are differnt.
e4s.translate.LabelSys	In development of core e4s system functions. Not recommended

When writing an application, you should not worry too much about as most functions of the e4s automatically convert yoer Strings to e4s.translate.LabelApp to register them for the translation mechanism.

How to involke translations:

Examples:

 // create a translation object and pass it to the print or println functions
 html.print(new LabelApp("Hello World"));

 // use the predefined functions to create translation objects
 html.print(LabelApp("Hello World"));

 // use the explicit translate(String) function similar to print(String)
 html.translate("Hello World");

 // use a variable
 String name = "Robert";
 LabelApp errormessage = new LabelApp("For user # this function is restricted",name);
 html.BODY().print(errormessage);

 // create a message that becomes translated
 html.Message(Message.ERROR_DATA,"There is an error!");
 
 // create an input field that automatically becomes translated
 FIEDSET fieldset = html.FIELDSET();
 fieldset.TEXTFIELD(new InputFieldName("TEST"),"Hello World",20);

 // this text will not become translated:
 html.print("Hello World");

 // this text will explicit not become translated:
 FIEDSET fieldset = html.FIELDSET();
 fieldset.TEXTFIELD(new InputFieldName("TEST"),new LabelNone("Hello World"),20);

Parameters in translations:

Translation is sometimes an easy translation of a word or a short sentance, e.g. "Enter your name here". But sometimes you want to use Strings for output that are combined out of translation environment including actual program environment, e.g. "Good morning Robert Siegel, please select your option". In this case, the String "Good morning" and ", please select your option" needs to be translated. In principal, you could write:

        String username = "Robert Siegel";
        html.translate("Good morning ");
        html.print(username);
        html.print(", please select your option");

But this is some overhead of code, it results in two Strings beeing translated without any logical relationship. But the biggest disadvantage is, that in some languages the sentence could be split up in a different way.

To avoid this, you can use the parameters provided in the constructor of e4s.translate.LabelApp:

        String username = "Robert Siegel";
        html.print(new LabelApp("Good morning #, please select your option",username));

Integration of external translation services:

When the following parameters are provided in your systems .ini file (e4s.e4sSettings), an external program can be included.

Parameter	Description	Example
TRANSLATION.URL	The URL for your translation program, including "tags" that will be replaced during runtime. <SLAN> stands for the source language code (e4s.application.Language) <DLAN> stands for the destination language code (e4s.application.Language) <TEXT> stands for the source text, this is the text to be translated.	http://babelfish.altavista.com/tr?doit=done&intl=1&lp=<SLAN>_<DLAN>&tt=urltext&trtext=<TEXT>
TRANSLATION.PREFIX	The result is somewhere included in a XML or HTML output String. You must define the sequence exactly as it appears before the result String..	<td bgcolor=white class=s><div style=padding:10px;>
TRANSLATION.POSTFIX	..and after the result String:	</div></td>
TRANSLATION.CREDITS	Include a .gif or .jpg file for credits of the translation service. Many free services require this by their license conditions.	http://us.i1.yimg.com/us.yimg.com/i/us/av/i/bf/systran-big-logo2.gif

The parameters in the url string will be replaced, according current values at runtime. Then it is expected, that the service will return a HTML page and the translation result is somewhere embedded in that HTML output and can be identified unique.

See also e4s.translate.externalTranslation

Please note, that you might require some license agreement for the translation services embedded! This is not part of the e4s, and it depends on the tool and license you require.

How to turn on translation editing:

Use function sessionCanEditTranslations in e4s.servlet.servletImplementation_Intf, see module e4s.application.sysmodule.moduleControlCenter.