IANA Language Tags for JavaScript
Based on BCP 47 (RFC 5646) and the latest IANA language subtag registry.
This project will be updated as the standards change.
JSON data
See the language-subtag-registry project for the underlying JSON data.
API
var tags = require('language-tags')
Note that all lookups and checks for tags and subtags are case insensitive. For formatting according to common conventions, see tag.format
.
tags(tag)
Check whether a hyphen-separated tag is valid and well-formed. Always returns a Tag
, which can be checked using the valid
method.
tags.check(tag)
Shortcut for tags(tag).valid()
. Return true
if the tag is valid, false
otherwise. For meaningful error output see tag.errors()
.
tags.subtags(subtag), tags.subtags(subtags)
Look up one or more subtags. Returns an array of Subtag
objects. Returns an empty array if all of the subtags are non-existent.
Calling tags.subtags('mt')
will return an array with two Subtag
objects: one for Malta (the 'region' type subtag) and one for Maltese (the 'language' type subtag).
> tags.subtags('mt');
[Subtag, Subtag]
> tags.subtags('bumblebee');
[]
To get or check a single subtag by type use tags.language(subtag)
, tags.region(subtag)
or tags.type(subtag, type)
.
tags.filter(subtags)
The opposite of tags.subtags(subtags)
. Returns an array of codes that are not registered subtags, otherwise returns an empty array.
> tags.filter(['en', 'Aargh']);
['Aargh']
tags.search(description, [all])
Search for tags and subtags by description. Supports either a RegExp object or a string for description
. Returns an array of Subtag
and Tag
objects or an empty array if no results were found.
Note that Tag
objects in the results represent 'grandfathered' or 'redundant' tags. These are excluded by default. Set the all
parameter to true
to include them.
Search is case-insensitive if description
is a string.
tags.languages(macrolanguage)
Returns an array of Subtag
objects representing all the 'language' type subtags belonging to the given 'macrolanguage' type subtag.
Throws an error if macrolanguage
is not a macrolanguage.
> tags.languages('zh');
[Subtag, Subtag...]
> tags.languages('en');
Error: 'en' is not a valid macrolanguage.
tags.language(subtag)
Convenience method to get a single 'language' type subtag. Can be used to validate an input value as a language subtag. Returns a Subtag
object or null
.
> tags.language('en');
Subtag
> tags.language('us');
null
tags.region(subtag)
As above, but with 'region' type subtags.
> tags.region('mt');
Subtag
> tags.region('en');
null
tags.type(subtag, type)
Get a subtag by type. Returns the subtag matching type
as a Subtag
object otherwise returns null
.
A type
consists of one of the following strings: 'language', 'extlang', 'script', 'region' or 'variant'. To get a 'grandfathered' or 'redundant' type tag use tags(tag)
.
> tags.type('zh', 'macrolanguage');
Subtag
> tags.type('zh', 'script');
null
tags.date()
Returns the file date for the underlying data, as a string.
> tags.date();
'2004-06-28'
Subtag
subtag.type()
Get the subtag type (either 'language', 'extlang', 'script', 'region' or 'variant'). See RFC 5646 section 2.2 for type definitions.
subtag.descriptions()
Returns an array of description strings (a subtag may have more than one description).
> tags.language('ro').descriptions();
['Romanian', 'Moldavian', 'Moldovan']
subtag.preferred()
Returns a preferred subtag as a Subtag
object if the subtag is deprecated. For example, ro
is preferred over deprecated mo
.
> tags.language('mo').preferred();
Subtag
subtag.script()
For subtags of type 'language' or 'extlang', returns a Subtag
object representing the language's default script. See RFC 5646 section 3.1.9 for a definition of 'Suppress-Script'.
subtag.scope()
Returns the subtag scope as a string, or null
if the subtag has no scope.
Tip: if the subtag represents a macrolanguage, you can use tags.languages(macrolanguage)
to get a list of all the macrolanguage's individual languages.
> tags.language('zh').scope();
'macrolanguage'
> tags.language('nah').scope();
'collection'
subtag.deprecated()
Returns a date string reflecting the deprecation date if the subtag is deprecated, otherwise returns null
.
> tags.language('ja').deprecated();
'2008-11-22'
subtag.added()
Returns a date string reflecting the date the subtag was added to the registry.
> tags.language('ja').added();
'2005-10-16'
Returns an array of comments, if any, otherwise returns an empty array.
> tags.language('nmf').comments();
['see ntx']
subtag.format()
Return the subtag code formatted according to the case conventions defined in RFC 5646 section 2.1.1.
- language codes are made lowercase ('mn' for Mongolian)
- script codes are made lowercase with the initial letter capitalized ('Cyrl' for Cyrillic)
- country codes are capitalized ('MN' for Mongolia)
Tag
tag.preferred()
If the tag is listed as 'deprecated' or 'redundant' it might have a preferred value. This method returns a Tag
object if so.
> tags('zh-cmn-Hant').preferred();
Tag
tag.type()
Returns grandfathered
if the tag is grandfathered, redundant
if the tag is redundant, and tag
if neither. For a definition of grandfathered and redundant tags, see RFC 5646 section 2.2.8.
tag.subtags()
Returns an array of subtags making up the tag, as Subtag
objects.
tag.language(), tag.region(), tag.script()
Shortcuts for tag.find('language')
, tag.find('region')
and tag.find('script')
.
tag.find(type)
Find a subtag of the given type from those making up the tag.
tag.valid()
Returns true
if the tag is valid, false
otherwise.
tag.errors()
Returns an array of Error
objects if the tag is invalid. The message
property of each is readable and helpful enough for UI output. The code
property can be checked against the Tag.ERR_*
constants. Each error will also have either a subtag
or tag
property with the code of the offending tag.
tag.format()
Format a tag according to the case conventions defined in RFC 5646 section 2.1.1.
> tags('en-gb').format();
'en-GB'
tag.deprecated()
For grandfathered or redundant tags, returns a date string reflecting the deprecation date if the tag is deprecated.
> tags('zh-cmn-Hant').deprecated();
'2009-07-29'
tag.added()
For grandfathered or redundant tags, returns a date string reflecting the date the tag was added to the registry.
tag.descriptions()
Returns an array of tag descriptions for grandfathered or redundant tags, otherwise returns an empty array.
Resources
Credits and collaboration
Copyright (c) 2013, Matthew Caruana Galizia.
The software part of this project is licensed under an MIT licence.
Comments, feedback and suggestions are welcome. Please feel free to raise an issue or pull request. Enjoy.