Class Instance: Locale

Contains methods and data necessary to provide localization.

Notes

• The locale sets are protected in a private variable that can only be altered using methods in Locale documented below. Though you can retrieve locale sets, which are objects, you should not alter these through assignment but instead use the .define method.
• Locale sets can contain any type of object, so, for instance, a language item could be an array, a function, a string, or even another class. Classes that make use of these items must be aware of the types of objects in the language file.
• Language items that are functions are executed and their results are returned. So if you execute Locale.get('Date.ordinal', 4), then the ordinal member will be executed and passed 4 as its argument. If ordinal is not a function, then its value will simply be returned.
• Users are encouraged to send in updates and additions to the MooTools team to help us grow this collection of translations.
• Predefined Locale sets follow this list as Locale codes.

Example language file

Below is an example language file from Locale.en-US.Date.js. Note that some members are arrays (months and days), others are strings, and one is even a function. Also note that some of the strings contain notation for variable substitution. Each class establishes it's own conventions for the language file that is required and is therefore required to document those conventions. Look for these at the bottom of the class's Locale documentation.

Locale.define('en-US', 'Date', {
 
    months: ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'],
    days: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
    dateOrder: ['month', 'date', 'year', '/'],
    AM: "AM",
    PM: "PM",
    //members can be functions; these will be executed and passed any arguments with .get(member[,args])
    ordinal: function(dayOfMonth){
        return (dayOfMonth > 3 && dayOfMonth < 21) ? 'th' : ['th', 'st', 'nd', 'rd', 'th'][Math.min(dayOfMonth % 10, 4)];
    },
    lessThanMinuteAgo: 'less than a minute ago'
 
});

Locale event: onChange

This event is fired whenever the current locale is changed for the user (for instance, from "en-US" to "es-ES") or whenever the current selected locale is updated with new data.

������:

Locale.addEvent('change', function(name){
    alert('Youre locale settings changed to ' + name);
});

Locale method: define

Defines properties for a given set in a given language.

Syntax

Locale.define(name, set, data);
// or
Locale.define(name, set, key, value);

Arguments

1. name - (string) the locale name you want to alter.
2. set - (string) the set you want to alter in that locale.
3. data - (object) the key/values object for the set and locale.
4. key - (string) the key of a property for the data object for the set and locale.
5. value - (mixed) the value of a property for the data object for the set and locale.

Example

Locale.define('en-US', 'Date', {
    months: ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'],
    days: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
    dateOrder: ['month', 'date', 'year', '/'],
    AM: "AM",
    PM: "PM"
});

Returns

• object - Locale Set instance

Locale method: use

Sets the current locale for the user.

Syntax

Locale.use(name);

Arguments

1. name - (string) the new locale name to use.

Returns

• object - Locale (the instance)

Example

Locale.use('nl-NL');

Locale method: getCurrent

Returns the locale name currently in use.

Syntax

Locale.getCurrent();

Returns

• object - the Locale Set object
  • name - string The Locale Set name (i.e. "en-US").

Example

Locale.getCurrent().name // 'en-US'

Locale method: get

Retrieves a set of locale properties for the current language or the whole set.

Syntax

Locale.get(key[, args]);

Arguments

1. key - (string: optional) The member you wish to retrieve. This should look like Set.key. This will use Object.getFromPath for nested properties.
2. args - (mixed: optional) A single value or an array of values that are passed to the language value (if it is not a function, these are ignored; if it is a function, these are passed);

Example

Locale.get('Date.dayAgo'); //"1 day ago"
Locale.get('Date.nested.property'); // the get method is using Object.getFromPath to find properties
Locale.get('Date.ordinal', 1); //"st" > as in "1st"
Locale.get('Date.dayAgo', 'foo'); //foo is ignored
Locale.get('Date'); //returns the object of key/values for Date in the current language

Returns

• If passed a valid set and key, returns the locale value for the given set (usually a string).
• If passed a valid set and no key, returns an object containing all the key/values in the translation.
• If passed a valid set, key, and arguments, passes the arguments to the value if it is a function and returns what it returns, otherwise returns the value.

Notes:

1. Dots '.' in the key argument can be used to find nested properties.

Locale method: inherit

It often occurs that localization data is based on another language. For example Spanish in Argentina has many similarities with Spanish or Number formatting in Europe is the same for lots of Europe countries. Therefore it is possible to inherit another locale data from another language. Locale.get will search trough the inherited locale names until a property is set.

Syntax:

Locale.inherit(name, parent[, set]);

���������:

1. name - (string) The locale name
2. parent - (string) The locale name to inherit from
3. set - (string, optional) If the locale data should only inherit for specific data sets, set this argument

Returns

• object - Locale (the instance)

������:

Locale.inherit('es-AR', 'es-ES');
 
// Only inherit for a specific data set
Locale.inherit('de-CH', 'de-DE', 'Number');

Locale method: list

Returns an array of languages currently supported.

Syntax

Locale.list();

Returns

• array an array of locale names (strings)