str = getText(text[,locale])
str = _(text[,locale])
This function is similar to the gettext() function in the standard Unix library for C/C++ and may be used to translate text strings into different languages. (The _() version is a shorthand alias, as it usually is in C and C++). Instead of the .po files used in C/C++, the JSUS getText() function accesses translated text through a system wide database server (which may also be accessed by non-JSUS programs via a UNIX socket). In addition, the JSUS function requires a formal text code at the beginning of the string, instead of using the default text itself as a key. In practice, this is much easier to manage within the development process and is just as fast in operation (because the database is memory-mapped).
A full text code consists of three separate elements — the text identifier and both a minor and major text "domain". These must all be valid JavaScript identifiers and each must be preceded by a dot (period) which serves as a separator, just like Internet domains. For example:
.mesgID.application.organization
In normal usage the last two, the minor and major components of the text domain, are typically omitted, after a default domain is established by an earlier call specifying only those two elements:
myVar = _('.bigApp.acmeSoftware');
This call both sets the default domain and returns its value (in case it is needed elsewhere in the program). This is customarily performed early in the program code and, thereafter, only the specific text id needs to be provided at the beginning of the input string. However, a full text code can always be used to override the default text domain, if any.
At least the text id must be provided at the beginning of any string for which translation is desired. Optionally, but usually, it may be followed by a single space and the default text to be used if translation is not possible (by convention, the default text should be in English). If the code is valid, and present in the database, getText() returns a string with the translated version of the text, according to either the locale specified as the second argument, or the current locale set for the program. If there is no translation for that locale present in the database, getText() returns the default text from the database. The default text from the input string is returned only if the text code is valid but there are no entries at all for that code in the database (or if the database is not available). In this case, only the default text is returned, without the text code and separating space. If the text code is invalid, the entire input string is returned to the caller, unchanged, including any invalid code. Finally, if only a valid text code is provided, and this cannot be located in the database, getText() returns a string with the text code, followed by default text of its own (in English).
Note that the ask(), say() and cry() functions all call _(), internally, for the strings they send to the user on stdout or stderr. In addition, the etc() function calls _() for all strings retrieved from the ETC database if they begin with a dot (but not ./ or ..). Similarly, the gulp() function internally executes _() on replacement macro values retrieved from a text file. (All of these functions support an optional second argument to provide the name of the required locale). Therefore, it is not necessary to enclose such strings in a separate _() function call.
Development note: The translation database manager is currently still under development. Until then, default text handling is fully implemented as described above. New JSUS programs should be written as though the database is already available, and will not need any changes once database development is complete. Simply inserting translation text into the database will suffice.