bcp-47-match

bcp-47-match

Match BCP 47 language tags with “language ranges” per RFC 4647, as done by the :lang() pseudo-class in CSS, or the Accept-Language HTTP header.

Related to bcp-47.

Installation

npm:

npm install bcp-47-match

Table of Contents

• Usage
• API
  • match.basicFilter(tags[, ranges])
  • match.extendedFilter(tags[, ranges])
  • match.lookup(tags, ranges)
• License

Usage

var match = require('bcp-47-match')

var basic = match.basicFilter
var extended = match.extendedFilter
var lookup = match.lookup

var tags = ['en-GB', 'de-CH', 'en', 'de']

console.log(basic(tags, '*')) // => [ 'en-GB', 'de-CH', 'en', 'de' ]
console.log(basic(tags, 'en')) // => [ 'en-GB', 'en' ]
console.log(basic(tags, 'en-GB')) // => [ 'en-GB' ]
console.log(basic(tags, ['en-GB', 'en'])) // => [ 'en-GB', 'en' ]
console.log(basic(tags, 'jp')) // => []

console.log(extended(tags, '*')) // => [ 'en-GB', 'de-CH', 'en', 'de' ]
console.log(extended(tags, 'en')) // => [ 'en-GB', 'en' ]
console.log(extended(tags, 'en-GB')) // => [ 'en-GB' ]
console.log(extended(tags, '*-GB')) // => [ 'en-GB' ]
console.log(extended(tags, ['en-GB', 'en'])) // => [ 'en-GB', 'en' ]
console.log(extended(tags, 'jp')) // => []

console.log(lookup(tags, 'en')) // => 'en'
console.log(lookup(tags, 'en-GB')) // => 'en-GB'
console.log(lookup(tags, ['en-GB', 'en'])) // => 'en-GB'
console.log(lookup(tags, ['en', 'en-GB'])) // => 'en'
console.log(lookup(tags, 'jp')) // => undefined

API

match.basicFilter(tags[, ranges])

See Basic Filtering spec

Match language tags to a list of simple ranges. Searches for matches between the first range and all tags, and continues with further ranges. Returns a list of matching tags in the order they matched.

View matching table

Basic Filter	*	de	de-CH	de-DE	de-*-DE	*-CH
de	✔︎	✔︎
de-CH	✔︎	✔︎	✔︎
de-CH-1996	✔︎	✔︎	✔︎
de-DE	✔︎	✔︎		✔︎
de-DE-1996	✔︎	✔︎		✔︎
de-DE-x-goethe	✔︎	✔︎		✔︎
de-Deva	✔︎	✔︎
de-Deva-DE	✔︎	✔︎
de-Latf-DE	✔︎	✔︎
de-Latn-DE	✔︎	✔︎
de-Latn-DE-1996	✔︎	✔︎
de-x-DE	✔︎	✔︎
en	✔︎
en-GB	✔︎
zh	✔︎
zh-Hans	✔︎
zh-Hant	✔︎

Parameters

• tags (string or Array.<string>) — List of BCP-47 tags
• ranges (string or Array.<string>) — List of RFC 4647 basic ranges (aka, matching /^(\*|[a-z]{1,8}(-[a-z0-9]{1,8})*)$/i)

Returns

Array.<string> — Possibly empty list of matching tags in the order they matched.

match.extendedFilter(tags[, ranges])

See Extended Filtering spec

Match language tags to a list of extended ranges. Searches for matches between the first range and all tags, and continues with further ranges.

View matching table

Extended Filter	*	de	de-CH	de-DE	de-*-DE	*-CH
de	✔︎	✔︎
de-CH	✔︎	✔︎	✔︎			✔︎
de-CH-1996	✔︎	✔︎	✔︎			✔︎
de-DE	✔︎	✔︎		✔︎	✔︎
de-DE-1996	✔︎	✔︎		✔︎	✔︎
de-DE-x-goethe	✔︎	✔︎		✔︎	✔︎
de-Deva	✔︎	✔︎
de-Deva-DE	✔︎	✔︎		✔︎	✔︎
de-Latf-DE	✔︎	✔︎		✔︎	✔︎
de-Latn-DE	✔︎	✔︎		✔︎	✔︎
de-Latn-DE-1996	✔︎	✔︎		✔︎	✔︎
de-x-DE	✔︎	✔︎
en	✔︎
en-GB	✔︎
zh	✔︎
zh-Hans	✔︎
zh-Hant	✔︎

Parameters

• tags (string or Array.<string>) — List of BCP-47 tags
• ranges (string or Array.<string>) — List of RFC 4647 extended ranges (aka, matching /^(\*|[a-z]{1,8})(-(\*|[a-z0-9]{1,8}))*$/i)

Returns

Array.<string> — Possibly empty list of matching tags in the order they matched.

match.lookup(tags, ranges)

See Lookup spec

Find the best language tag that matches a list of ranges. Searches for a match between the first range and all tags, and continues with further ranges. Returns the first match, if any.

View matching table

Lookup	*	de	de-CH	de-DE	de-*-DE	*-CH
de		✔︎︎	✔︎︎	✔︎	✔︎	✔︎
de-CH			✔︎			✔︎
de-CH-1996						✔︎
de-DE				✔︎		✔︎
de-DE-1996						✔︎
de-DE-x-goethe						✔︎
de-Deva						✔︎
de-Deva-DE						✔︎
de-Latf-DE						✔︎
de-Latn-DE						✔︎
de-Latn-DE-1996						✔︎
de-x-DE						✔︎
en						✔︎
en-GB						✔︎
zh						✔︎
zh-Hans						✔︎
zh-Hant						✔︎

Parameters

• tags (string or Array.<string>) — List of BCP-47 tags
• ranges (string or Array.<string>) — List of RFC 4647 basic ranges (but * is ignored)

Returns

string? — The first matching tag in tags, or undefined otherwise.

License

MIT © Titus Wormer