# Class: I18n

## jala.I18n()

This class provides various functions and macros for internationalization of Helma applications.

## Constructor

#### new I18n()

Constructs a new instance of jala.I18n

Source:
  - jala/code/I18n.js, line 41

### Methods

#### formatMessage(message, values)

Converts the message passed as argument into an instance of java.text.MessageFormat, and formats it using the replacement values passed.

##### Parameters:

Name | Type | Description
--- | --- | ---
`message` | String | The message to format
`values` | Array | An optional array containing replacement values

Source:
  - jala/code/I18n.js, line 221
See:
  - http://java.sun.com/j2se/1.5.0/docs/api/java/text/MessageFormat.html

##### Returns:

The formatted message or, if the formatting fails, the message passed as argument.

#### getCatalog()

Helper method to get the message catalog corresponding to the actual locale.

Source:
  - jala/code/I18n.js, line 191

##### Returns:

The message catalog.

#### getLocale()

Returns the locale for the given id, which is expected to follow the form `language[_COUNTRY][_variant]`, where `language` is a valid ISO Language Code (eg. "de"), `COUNTRY` a valid ISO Country Code (eg. "AT"), and variant an identifier for the variant to use.

Source:
  - jala/code/I18n.js, line 129

##### Returns:

The locale for the given id

#### getLocaleGetter()

Get the method for retrieving the locale.

Source:
  - jala/code/I18n.js, line 92

##### Returns:

The getter method

#### getMessages()

Get the message object.

Source:
  - jala/code/I18n.js, line 70

##### Returns:

The object containing the messages

#### gettext(key)

Returns a localized message for the message key passed as argument. If no localization is found, the message key is returned. Any additional arguments passed to this function will be used as replacement values during message rendering. To reference these values the message can contain placeholders following "{number}" notation, where `number` must match the number of the additional argument (starting with zero).

##### Parameters:

Name | Type | Description
--- | --- | ---
`key` | String | The message to localize

Source:
  - jala/code/I18n.js, line 267
See:
  - #translate
  - #formatMessage

##### Returns:

The translated message

#### markgettext(key)

A simple proxy method which is used to mark a message string for the i18n parser as to be translated.

##### Parameters:

Name | Type | Description
--- | --- | ---
`key` | String | The message that should be seen by the i18n parser as to be translated.

Source:
  - jala/code/I18n.js, line 304

##### Returns:

The message in unmodified form

#### message_macro()

Returns a translated message. The following macro attributes are accepted:

- text: The message to translate (required)
- plural: The plural form of the message
- values: A list of replacement values. Use a comma to separate more than one value. Each value is either interpreted as a global property (if it doesn't containg a dot) or as a property name of the given macro handler object (eg. "user.name"). If the value of the property is a HopObject or an Array this macro uses the size() resp. length of the object, otherwise the string representation of the object will be used.

Source:
  - jala/code/I18n.js, line 326
See:
  - #gettext
  - #ngettext

##### Returns:

The translated message

#### ngettext(singularKey, pluralKey, amount)

Returns a localized message for the message key passed as argument. In contrast to gettext() this method can handle plural forms based on the amount passed as argument. If no localization is found, the appropriate message key is returned. Any additional arguments passed to this function will be used as replacement values during message rendering. To reference these values the message can contain placeholders following "{number}" notation, where `number` must match the number of the additional argument (starting with zero).

##### Parameters:

Name | Type | Description
--- | --- | ---
`singularKey` | String | The singular message to localize
`pluralKey` | String | The plural form of the message to localize
`amount` | Number | The amount which is used to determine whether the singular or plural form of the message should be returned.

Source:
  - jala/code/I18n.js, line 291
See:
  - #translate
  - #formatMessage

##### Returns:

The translated message

#### setHandler(handler)

Set (overwrite) the default handler containing the messages (ie. a vanilla EcmaScript object).

##### Parameters:

Name | Type | Description
--- | --- | ---
`handler` | Object | The handler containing the message object

Deprecated:
  - Use #setMessages instead
Source:
  - jala/code/I18n.js, line 116

#### setLocaleGetter(func)

Set the method for retrieving the locale.

##### Parameters:

Name | Type | Description
--- | --- | ---
`func` | function | The getter method

Source:
  - jala/code/I18n.js, line 78

#### setMessages(msgObject)

Overwrite the default object containing the messages (ie. a vanilla EcmaScript object).

##### Parameters:

Name | Type | Description
--- | --- | ---
`msgObject` | Object | The object containing the messages

Source:
  - jala/code/I18n.js, line 61

#### translate(key, plural, amount)

Tries to "translate" the given message key into a localized message.

##### Parameters:

Name | Type | Description
--- | --- | ---
`key` | String | The message to translate (required)
`plural` | String | The plural form of the message to translate
`amount` | Number | A number to determine whether to use the singular or plural form of the message

Source:
  - jala/code/I18n.js, line 156

##### Returns:

The localized message or the appropriate key if no localized message was found