OpenEuphoria

8.19 Locale Routines

8.19.1 Message translation functions

8.19.1.1 set_lang_path

include std/locale.e
namespace locale
public procedure set_lang_path(object pp)

Set the language path.

Parameters:

1. pp : an object, either an actual path or an atom.

Comments:

When the language path is not set, and it is unset by default, set() does not load any language file.

See Also:

set

8.19.1.2 get_lang_path

include std/locale.e
namespace locale
public function get_lang_path()

Get the language path.

Returns:

An object, the current language path.

See Also:

get_lang_path

8.19.1.3 lang_load

include std/locale.e
namespace locale
public function lang_load(sequence filename)

Load a language file.

Parameters:

1. filename : a sequence, the name of the file to load. If no file extension is supplied, then ".lng" is used.

Returns:

A language map, if successful. This is to be used when calling translate().

If the load fails it returns a zero.

Comments:

The language file must be made of lines which are either comments, empty lines or translations. Note that leading whitespace is ignored on all lines except continuation lines.

• Comments are lines that begin with a # character and extend to the end of the line.
• Empty Lines are ignored.
• Translations have two forms ...

keyword translation_text

In which the 'keyword' is a word that must not have any spaces in it.

keyphrase = translation_text

In which the 'keyphrase' is anything up to the first '=' symbol.

It is possible to have the translation text span multiple lines. You do this by having '&' as the last character of the line. These are placed by newline characters when loading.

Example:

# Example translation file
#


hello Hola
world Mundo
greeting %s, %s!

help text = &
This is an example of some &
translation text that spans &
multiple lines.

# End of example PO #2

See Also:

translate

8.19.1.4 set_def_lang

include std/locale.e
namespace locale
public procedure set_def_lang(object langmap)

Sets the default language (translation) map

Parameters:

1. langmap : A value returned by lang_load(), or zero to remove any default map.

Example:

set_def_lang( lang_load("appmsgs") )

8.19.1.5 get_def_lang

include std/locale.e
namespace locale
public function get_def_lang()

Gets the default language (translation) map

Parameters:

none.

Returns:

An object, a language map, or zero if there is no default language map yet.

Example:

object langmap = get_def_lang()

8.19.1.6 translate

include std/locale.e
namespace locale
public function translate(sequence word, object langmap = 0, object defval = "",
        integer mode = 0)

Translates a word, using the current language file.

Parameters:

1. word : a sequence, the word to translate.
2. langmap : Either a value returned by lang_load() or zero to use the default language map
3. defval : a object. The value to return if the word cannot be translated. Default is "". If defval is PINF then the word is returned if it can't be translated.
4. mode : an integer. If zero (the default) it uses word as the keyword and returns the translation text. If not zero it uses word as the translation and returns the keyword.

Returns:

A sequence, the value associated with word, or defval if there is no association.

Example 1:

sequence newword
newword = translate(msgtext)
if length(msgtext) = 0 then
   error_message(msgtext)
else
   error_message(newword)
end if

Example 2:

error_message(translate(msgtext, , PINF))

See Also:

set, lang_load

8.19.1.7 trsprintf

include std/locale.e
namespace locale
public function trsprintf(sequence fmt, sequence data, object langmap = 0)

Returns a formatted string with automatic translation performed on the parameters.

Parameters:

1. fmt : A sequence. Contains the formatting string. see printf() for details.
2. data : A sequence. Contains the data that goes into the formatted result. see printf for details.
3. langmap : An object. Either 0 (the default) to use the default language maps, or the result returned from lang_load() to specify a particular language map.

Returns:

A sequence, the formatted result.

Comments:

This works very much like the sprintf() function. The difference is that the fmt sequence and sequences contained in the data parameter are translated before passing them to sprintf. If an item has no translation, it remains unchanged.

Further more, after the translation pass, if the result text begins with "__", the "__" is removed. This method can be used when you do not want an item to be translated.

Examples:

-- Assuming a language has been loaded and
--   "greeting" translates as '%s %s, %s'
--   "hello"  translates as "G'day"
--   "how are you today" translates as "How's the family?"
sequence UserName = "Bob"
sequence result = trsprintf( "greeting", {"hello", "__" & UserName, "how are you today"})
   --> "G'day Bob, How's the family?"

8.19.2 Time/Number Translation

8.19.2.1 set

include std/locale.e
namespace locale
public function set(sequence new_locale)

Set the computer locale, and possibly load appropriate translation file.

Parameters:

1. new_locale : a sequence representing a new locale.

Returns:

An integer, either 0 on failure or 1 on success.

Comments:

Locale strings have the following format: xx_YY or xx_YY.xyz . The xx part refers to a culture, or main language/script. For instance, "en" refers to English, "de" refers to German, and so on. For some language, a script may be specified, like in "mn_Cyrl_MN" (mongolian in cyrillic transcription).

The YY part refers to a subculture, or variant, of the main language. For instance, "fr_FR" refers to metropolitan France, while "fr_BE" refers to the variant spoken in Wallonie, the French speaking region of Belgium.

The optional .xyz part specifies an encoding, like .utf8 or .1252 . This is required in some cases.

8.19.2.2 get

include std/locale.e
namespace locale
public function get()

Get current locale string

Returns:

A sequence, a locale string.

See Also:

set

8.19.2.3 money

include std/locale.e
namespace locale
public function money(object amount)

Converts an amount of currency into a string representing that amount.

Parameters:

1. amount : an atom, the value to write out.

Returns:

A sequence, a string that writes out amount of current currency.

Example 1:

-- Assuming an en_US locale
money(1020.5) -- returns"$1,020.50"

See Also:

set, number

8.19.2.4 number

include std/locale.e
namespace locale
public function number(object num)

Converts a number into a string representing that number.

Parameters:

1. num : an atom, the value to write out.

Returns:

A sequence, a string that writes out num.

Example 1:

-- Assuming an en_US locale
number(1020.5) -- returns "1,020.50"

See Also:

set, money

8.19.2.5 datetime

include std/locale.e
namespace locale
public function datetime(sequence fmt, datetime :datetime dtm)

Formats a date according to current locale.

Parameters:

1. fmt : A format string, as described in datetime:format
2. dtm : the datetime to write out.

Returns:

A sequence, representing the formatted date.

Example 1:

include std/datetime.e

datetime("Today is a %A", datetime:now())

See Also:

datetime:format

8.19.2.6 get_text

include std/locale.e
namespace locale
public function get_text(integer MsgNum, sequence LocalQuals = {}, sequence DBBase = "teksto")

Get the text associated with the message number in the requested locale.

Parameters:

1. MsgNum : An integer. The message number whose text you are trying to get.
2. LocalQuals : A sequence. Zero or more locale codes. Default is {}.
3. DBBase: A sequence. The base name for the database files containing the locale text strings. The default is "teksto".

Returns:

A string sequence, the text associated with the message number and locale.
The integer zero, if associated text can not be found for any reason.

Comments:

• This first scans the database(s) linked to the locale codes supplied.
• The database name for each locale takes the format of "<DBBase>_<Locale>.edb" so if the default DBBase is used, and the locales supplied are {"enus", "enau"} the databases scanned are "teksto_enus.edb" and "teksto_enau.edb". The database table name searched is "1" with the key being the message number, and the text is the record data.
• If the message is not found in these databases (or the databases don't exist) a database called "<DBBase>.edb" is searched. Again the table name is "1" but it first looks for keys with the format {<locale>,msgnum} and failing that it looks for keys in the format {"", msgnum}, and if that fails it looks for a key of just the msgnum.