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.

Contents

• Install
• Use
• API
  • basicFilter(tags[, ranges='*'])
  • extendedFilter(tags[, ranges='*'])
  • lookup(tags, ranges)
• Related
• License

Install

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

npm:

npm install bcp-47-match

Use

import {basicFilter, extendedFilter, lookup} from 'bcp-47-match'

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

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

console.log(extendedFilter(tags, '*')) // => [ 'en-GB', 'de-CH', 'en', 'de' ]
console.log(extendedFilter(tags, 'en')) // => [ 'en-GB', 'en' ]
console.log(extendedFilter(tags, 'en-GB')) // => [ 'en-GB' ]
console.log(extendedFilter(tags, '*-GB')) // => [ 'en-GB' ]
console.log(extendedFilter(tags, ['en-GB', 'en'])) // => [ 'en-GB', 'en' ]
console.log(extendedFilter(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

This package exports the following identifiers: basicFilter, extendedFilter, lookup. There is no default export.

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.

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.

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.

Related

• bcp-47 — Parse and serialize BCP 47 language tags
• bcp-47-normalize — Normalize, canonicalize, and format BCP 47 tags
• iso-3166 — ISO 3166 codes
• iso-639-2 — ISO 639-2 codes
• iso-639-3 — ISO 639-3 codes
• iso-15924 — ISO 15924 codes
• un-m49 — UN M49 codes

License

MIT © Titus Wormer