Phrase Translation
Overview
The EUS Toolkit provides the means for maintaining applications across multiple languages without duplicating code sets for each language. The Phrase Translation Utility works as part of the Input Subsystem and is active when the global string (TRANSLATE) exists. A value in the string is not needed as long as it exists in the global string table as a null string.
If the (LANGUAGE) global string is set to "am", no translation takes place because the EUS Toolkit defaults to "am" (American English) assumptions. The actual presence of foreign words in prompt strings will not trigger the Phrase Translation Utility; (TRANSLATE) must exist in the global string table, and (LANGUAGE) must be set to some language code other than "am."
Phrase Translation is a state of the EUS Toolkit and TAOS and is either active or inactive. EUS Toolkit programs such as the menu driver, however, attempt to use Phrase Translation for internal messages, regardless of what state it is set to.
Implementing Phrase Translation
Although phrase translation occurs under the conditions given above, the developer can control the invocation of this utility at a lower level. For example, the _ask.utl utility accepts an argument "t", which tells it not to invoke Phrase Translation, though the global string table entries show that the utility is active.
An alternate method of control is to create the (NOTRANSLATE) global string for the duration of a process that uses prompts and/or messages that should not be translated. This global string is used by the _tlate.utl utility and interactively prompts the developer for translation phrases whenever it fails to locate a translation in its database, providing additional control for the developer. Only _ask.utl and _warn.utl acknowledge (NOTRANSLATE) and will not perform translations if the global string exists.
The error processing system enables the developer to translate constants without concern for variables. For example, if a file, utdata, cannot be found, and the application attempts to display a warning, the developer can use the following code to ensure that the file name is not translated along with the rest of the error message:
FILENAME$="utdata"
CALL STBL("BBEXT")+"_warn.utl","Unable to locate ",$$,"c"
CALL STBL("BBEXT")+"_warn.utl",FILENAME$,$$,"v"
CALL STBL("BBEXT")+"_warn.utl",$$,$$,"f"
The above example translates only the first line but does not translate the variable.
CALL STBL("BBEXT")+"_warn.utl","Unable to locate utdata"
This example attempts to translate the entire message, including the variable.
If an application uses the _saywarn.utl utility to display immediate mode messages, these are also translated under the automated conditions noted above. However, if variables are used to help complete the messages, use _warn.utl to ensure that critical information is given to the user.
The _yesno.utl utility automatically attempts to translate the values "YES" and "NO" but relies on the argument "t" to attempt to translate the question passed to it or not.
How Phrase Translation Works
The _tlate.utl utility maintains a special data file for each language code. The file names are composed of the form tlate.+(LANGUAGE). The translation files are keyed files and use the base language (type "am") phrases to be translated as the keys for the file, while the conversion language phrases are stored as data in the records. Each phrase stored for translation can be no more than 50 characters long.
_tlate.utl accepts only one parameter, the phrase requiring translation, to be passed and must be in the form of a string variable (a string literal cannot be replaced by a translation).
If the (LANGUAGE) global string does not contain "am," the appropriate translation file is searched for. If found, the file is opened and searched for the phrase to be translated. A successful lookup results in the passed phrase being replaced with the translation stored in the file. If the file cannot be located, _tlate.utl creates it automatically. If the phrase to be translated is not in the file, _tlate.utl exits without attempting the translation.
To load the translation files with data, create a global string (SYSTEM), change the global string (LANGUAGE) to hold a value other than "am", and create the global string (TRANSLATE).
While these global strings exist, _tlate.utl prompts the user for translation phrases for everything passed to it that cannot be found in the translation file. It is, therefore, possible to write an interface program that uses _ask.utl to prompt for a phrase to be translated (_ask.utl passes the phrase to _tlate.utl), sets the (NOTRANSLATE) global string, uses _ask.utl to verify that the translation is correct, deletes the record if it is not correct, and clears the (NOTRANSLATE) global string before looping back to prompt for the next phrase.
The inclusion of variable data in translation phrases is not recommended because an inordinate number of translations may be required. Phrases that include variable data should be broken down into components so that the literal portions are translated only once for each language. The variable data itself can be translated as required.