# OpenEuphoria Manual

## Euphoria v4.1

routine or constant name search

| Up |  |  | TOC | Index
<< 7 Included Tools | < 8.18 Sorting | Up: 8 API Reference | 8.20 Locale Names > | 9 Release Notes >>

## 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)

sets 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()

gets 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)

loads 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 1:

    # 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 1:

    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 1:

    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 not 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 function can be used when you do not want an item to be translated.

##### Example 1:

    -- 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 and Number Translation

#### 8.19.2.1 set

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

sets the computer locale, and possibly loads an 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 or script. For instance, `"en"` refers to English, `"de"` refers to German, and so on. For some languages, a script may be specified, like `"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()

gets the 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")

gets 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 or databases 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 do not 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`.

| Up |  |  | TOC | Index
<< 7 Included Tools | < 8.18 Sorting | Up: 8 API Reference | 8.20 Locale Names > | 9 Release Notes >>