inter
v2.1.0
Published
inter =====
Downloads
18,797
Keywords
Readme
inter
A JavaScript locale library that can be used to render dates, date and date-time intervals, numbers, lists, and more. Also contains localized display names for countries, regions, languages, time zones, and currencies. Most of the informations comes from the Unicode CLDR (Common Localization Data Repository) and is extracted using the cldr module.
Installation
Make sure you have node.js and npm installed, then run:
$ npm install -g inter
Usage
To use inter in node.js, just require the library and use the load
method to get an inter
object with information about a specific
locale:
var localeId = 'en_US',
inter = require('inter').load(localeId);
In the browser you'll most likely want to build a version with only
the specific features and locales you need. There's a buildInter
script in the package that's useful for that. You can build one
completely self-contained file per locale by specifying --type
browser
.
You can also build a single file with the data for all locales using
--type bundle
. The active locale will be determined by the value of
the LOCALEID
variable when the bundle is loaded into the
browser. This is tailored especially for assetgraph-builder
with the --locales
switch. Working with a single file is convenient
during development. When doing a production build UglifyJS' dead code
elimination will be used to strip the library down after
buildProduction
has created separate versions of your JavaScript
for each locale.
Reference
inter.countries
An array of objects representing country display names. The array is ordered by display name and contains some additional properties:
require('inter').load('da').countries[0];
{ id: 'AF',
displayName: 'Afghanistan',
regionId: '034',
hasTimeZones: true }
inter.getCountry(countryId)
Get info about a specific country (queried by ID):
require('inter').load('sv').getCountry('SE');
{ id: 'SE',
displayName: 'Sverige',
regionId: '154',
hasTimeZones: true }
inter.regions
An array of objects with region display names and some additional info. The array is
ordered by display name. Superset of inter.countries
and
inter.regions
.
require('inter').load('en_US').regions;
[ { id: '002',
displayName: 'Africa',
hasTimeZones: false },
{ id: '019',
displayName: 'Americas',
hasTimeZones: false },
[...]
{ id: '001',
displayName: 'World',
hasTimeZones: false } ]
inter.getRegion(regionId)
Get info about a specific region, queried by ID:
require('inter').load('en_US').getRegion('018');
{ id: '018',
displayName: 'Southern Africa',
hasTimeZones: false }
inter.territories
An array of objects with territory display names and some additional info. The array is
ordered by display name and contains some additional
properties. Superset of inter.countries
and inter.regions
.
require('inter').load('en_US').territories;
[ { id: 'AF',
displayName: 'Afghanistan',
regionId: '034',
hasTimeZones: true },
{ id: '002',
displayName: 'Africa',
hasTimeZones: false },
[...]
{ id: 'AX',
displayName: 'Åland Islands',
regionId: '154',
hasTimeZones: true } ]
inter.getTerritory(territoryId)
Get info about a specific territory, queried by ID (can be either a region or a country):
require('inter').load('en_US').getTerritory('US');
{ id: 'US',
displayName: 'United States',
regionId: '021',
hasTimeZones: true }
inter.timeZones
An array of objects representing all available time zone display names plus some additional info (Olson/tzdata ID, UTC offset, and the ID of the country it belongs to). The array is ordered by UTC offset and secondarily by display name:
require('inter').load('da').timeZones;
[ { id: 'Pacific/Midway',
utcStandardOffsetSeconds: -39600,
displayName: 'Midway',
countryId: 'UM' },
[...]
{ id: 'Pacific/Kiritimati',
regionId: '057',
utcStandardOffsetSeconds: 50400,
displayName: 'Kiritimati',
countryId: 'KI' } ]
inter.getTimeZone(timeZoneId)
Get info about a specific time zone (queried by its Olson/tzdata ID):
require('inter').load('da').getTimeZone('Europe/Copenhagen');
{ id: 'Europe/Copenhagen',
regionId: '154',
utcStandardOffsetSeconds: 3600,
displayName: 'København',
countryId: 'DK' }
inter.languages
An array of objects representing all available language display names plus some additional info. The array is ordered by display name:
require('inter').load('en_US').languages;
[ { id: 'aa',
displayName: 'Afar',
nativeDisplayName: 'Qafar' },
{ id: 'ab', displayName: 'Abkhazian' },
{ id: 'ace', displayName: 'Achinese' },
[...]
{ id: 'zxx',
displayName: 'No linguistic content' },
{ id: 'zza', displayName: 'Zaza' } ]
inter.getLanguage(languageId)
Get info about a specific language, queried by its ID:
require('inter').load('en_US').getLanguage('zh_hans');
{ id: 'zh_hans',
displayName: 'Simplified Chinese',
nativeDisplayName: '简体中文' }
inter.currencies
An array of objects with all available currency display names, including ids and symbols and instructions for displaying different quantities:
require('inter').load('sv').currencies;
[ { id: 'AWG',
displayName: 'Aruba-gulden',
one: 'Aruba-florin',
other: 'Aruba-floriner' },
{ id: 'BSD',
displayName: 'Bahamas-dollar',
symbol: 'BS$',
one: 'Bahamas-dollar',
other: 'Bahamas-dollar' },
[...]
{ id: 'DDM',
displayName: 'östtysk mark',
one: 'östtysk mark',
other: 'östtyska mark' } ]
inter.getCurrency(currencyId)
Get info about a specific currency, queried by its ID:
require('inter').load('ar').getCurrency('ZRN');
{ id: 'ZRN',
displayName: 'زائير زائيري جديد',
symbol: undefined,
zero: 'زائير زائيري جديد',
one: 'زائير زائيري جديد',
two: 'زائير زائيري جديد',
few: 'زائير زائيري جديد',
many: 'زائير زائيري جديد',
other: 'زائير زائيري جديد' }
inter.scripts
An array of objects with all available script display names, including IDs:
require('inter').load('en_US').scripts;
[ { id: 'Afak', displayName: 'Afaka' },
{ id: 'Hluw',
displayName: 'Anatolian Hieroglyphs' },
[...]
{ id: 'Wole', displayName: 'Woleai' },
{ id: 'Yiii', displayName: 'Yi' } ]
inter.getScript(scriptId)
Get info about a specific script, queried by its ID:
require('inter').load('en_US').getScript('Sgnw');
{ id: 'Sgnw', displayName: 'SignWriting' }
inter.renderSpelloutNumbering(number)
require('inter').load('en_US').renderSpelloutNumbering(53723);
'fifty-three thousand seven hundred twenty-three'
The library must be built with the --rbnf
switch.
inter.renderDigitsOrdinal(number)
require('inter').load('en_US').renderDigitsOrdinal(42);
'42nd'
The library must be built with the --rbnf
switch.
inter.pluralRule(number)
Determine the locale's plural form for a given number, eg. "one"
,
"two"
, "few"
, "zero"
, "many"
, or "other"
.
See the LDML spec for more information.
The library must be built with the --pluralrules
switch.
inter.renderList(itemArray[, 'unit'|'unitShort'|'unitNarrow'|'default'])
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).
inter.renderUnit(number, 'durationWeek'|'energyJoule'|'frequencyMegahertz'|...)
inter.getUnitRenderer('durationWeek'|'energyJoule'|'frequencyMegahertz'|...)
Render (or get a renderer function for) a specific unit. The
locale library must be built with the --unitpatterns
switch.
Example:
inter.getUnitRenderer('durationWeek')(1); // '1 week' (en_US)
inter.getUnitRenderer('durationMonth')(5); // '5 months' (en_US)
inter.renderUnit(1, 'durationWeek'); // '1 week' (en_US)
inter.renderNumber(number[, numberFormat[, numberSystemId]])
inter.getNumberRenderer([numberFormat[, numberSystemId]])
Render (or get a renderer function for) a number according to the specified ICU DecimalFormat (defaults to the locale standard number format for the locale).
inter.renderPercentage(number[, numDecimals[, numberSystemId]])
inter.getPercentageRenderer([numDecimals[, numberSystemId]])
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)
inter.renderFileSize(number[, numDecimals])
inter.getFileSizeRenderer([numDecimals])
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)
inter.renderDate(date, dateFormatId)
inter.getDateRenderer(dateFormatId)
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)
inter.renderDateInterval(dateInterval, dateFormatId)
inter.getDateIntervalRenderer(dateFormatId)
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
inter.tokenizePattern(patternString)
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}]
inter.getPatternRenderer(patternString)
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'
inter.tokenizeDateFormat(icuDateFormat)
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'}]
inter.getDateFormat(formatId)
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)
License
inter is licensed under a standard 3-clause BSD license -- see the
LICENSE
-file for details.