buildlocale

buildlocale ===========

buildlocale

A module that extracts a bunch of information from the CLDR database and builds a JavaScript library (called inter) that can be used to render dates, date and date-time intervals, numbers, lists, and more.

Intended for use with buildProduction --locale (see AssetGraph-builder), but can also be used on its own.

Installation and building

Make sure you have node.js and npm installed, then run:

$ npm install -g buildlocale

You now have the buildLocale binary in your $PATH.

Next up you need to download a CLDR release or checkout the Subversion repo.

Next up, build your custom library by running buildLocale and tell it where to find your CLDR files and which locales and features you want:

buildLocale --cldrpath /path/to/cldr/root/dir -o myLocaleLib.js --locale en,da,fr --localeidvar LOCALEID --dateformats --numberformats ...

This produces a single (large) JavaScript file containing all the features for all the locales. The value of the JavaScript variable theLocaleId will determine which locale will become active. Set it before myLocaleLib.js is loaded.

To cut down the size of the locale library for production use I recommend using assetgraph-builder (buildProduction --locale ...) or uglifyjs myLocaleLib.js --define LOCALEID=\"fr\" etc. to produce an optimized version for each locale (I've been told that Closure compiler has a similar feature).

Further buildLocale options:

--dateformatsInclude date and time formats (adds inter.dateFormats and a bunch of methods, see below) --dateintervalformatsInclude date and time interval formats (adds inter.dateIntervalFormats and a bunch of methods). --numberformatsInclude number formats (adds inter.numberSymbols, inter.getNumberRenderer, inter.getFileSizeRenderer, and inter.getPercentageRenderer) --delimitersInclude quotation delimiters (adds inter.delimiters) --listpatternsInclude list formats (inter.listPatterns and inter.renderList) --unitpatternsInclude unit patterns (inter.unitPatterns and inter.getUnitRenderer) --timezonesInclude time zone info and display names (inter.timeZones) --countriesInclude country info and display names (inter.countries) --regionsInclude region info and display names (inter.regions) --localesInclude locale info and display names (inter.locales) --localesincludedonlyModifies --locales to only include information about the locales included in the build. Useful for displaying a list of the supported locales in a web app while keeping down size of the library --currenciesInclude currency info and display names (inter.currencies) --pluralrulesInclude plural rules (inter.getQuantity) --exemplarcharactersInclude exemplar characters (inter.exemplarCharacters)

Usage

Render a list of items using the list patterns. The locale library must be built with the --listpatterns switch.

Example:

inter.renderList(['foo', 'bar', 'quux']); // "foo, bar, and quux" (en_US). 

Render (or get a renderer function for) a specific unit of time. The locale library must be built with the --dateformats switch.

Example:

inter.getUnitRenderer('week')(1); // '1 week' (en_US) 
inter.getUnitRenderer('month')(5); // '5 months' (en_US) 
inter.renderUnit(1, 'week'); // '1 week' (en_US) 

Render (or get a renderer function for) a percentage according to the number format and percent char of the locale. The library must be built with the --numberformats switch.

Example:

inter.getPercentageRenderer(1)(1.0056); // '105.6 %' (en_US) 
inter.renderPercentage(1.0056, 1); // '105.6 %' (en_US) 

Render (or get a renderer function for) a number of bytes according to the number format of the locale. The units themselves (bytes, KB, MB, etc.) aren't localized yet, sorry. The library must be built with the --numberformats switch.

Example:

inter.getFileSizeRenderer(1)(100000); // '97.7 KB' (en_US) 
inter.renderFileSize(100000, 1); // '97.7 KB' (en_US) 

Render (or get a renderer function for) one of the locale's standard full/long/medium/short time or date formats, or a locale-specifc format specified by a CLDR dateFormatItem id. The library must be built with the --dateformats switch.

Examples:

var aprilFourth = new Date(2010, 3, 4);
inter.getDateRenderer('mediumTime')(new Date(2010, 5, 7, 22, 30); // '10:30:00 pm' (en_US) 
inter.getDateRenderer('longDate')(new Date(2010, 5, 7, 22, 30); // 'June 7, 2010' (en_US) 
inter.renderDate(aprilFourth, 'fullDate'); // "Sunday, April 4, 2010" (en_US) 
inter.renderDate(aprilFourth, 'shortTime'); // "12:00 am" (en_US) 
inter.renderDate(aprilFourth, 'MMMMEd'); // "Sun, April 4" (en_US) 

Render (or get a renderer function for) a date or date-time interval that uses one of the locale's standard full/long/medium/short time or date formats, or a locale-specific format specified by a CLDR dateFormatItem id (see some examples). The library must be built with the --dateintervalformats switch.

Examples:

var dateIntervalRenderer = inter.getDateIntervalRenderer("yMMMM"),
    januaryThroughApril = {start: new Date(2010, 0, 1), end: new Date(2010, 4, 0)};
dateIntervalRenderer(januaryThroughApril); // "January-April 2010" (en_US) 
 
inter.renderDateInterval({
    start: new Date(2012, 9, 7, 9, 30),
    end: new Date(2012, 9, 7, 11, 30)
}, 'hm'); // "9:30–11:30 am" (en_US) 

Additional helper methods

Helper function for tokenizing an ICU pattern with placeholders.

Example:

inter.tokenizePattern('My name is {0}'); // [{type: 'text', value: 'My name is '}, {type: 'placeHolder', value: 0}] 

Get an optimized function for rendering a specific pattern. The function accepts the placeholder values as arguments.

Example:

inter.getPatternRenderer('My name is {0}')('George'); // 'My name is George' 

Helper function for parse a date format into text and field tokens. The locale library must be built with the --dateformats switch.

Example:

inter.tokenizeDateFormat('dddd-m')); // [{type: 'field', value: 'dddd'}, {type: 'text', value: '-'}, {type: 'field', value: 'm'}] 

Get one of the locale's standard full/long/medium/short time or date formats, or a locale-specific format specified by a CLDR dateFormatItem id (see see some examples). The locale library must be built with the --dateformats switch.

Examples:

inter.getDateFormat('fullDate'); // 'l, F j, Y' (en_US) 
inter.getDateFormat('yMMdd'); // 'MM/dd/y' (en_US) 
inter.getDateFormat('mediumTime'); // 'h:mm:ss a' (en_US) 

buildlocale is licensed under a standard 3-clause BSD license -- see the LICENSE-file for details.