diff options
| author | Shipwreckt <me@shipwreckt.co.uk> | 2025-10-31 20:02:14 +0000 |
|---|---|---|
| committer | Shipwreckt <me@shipwreckt.co.uk> | 2025-10-31 20:02:14 +0000 |
| commit | 7a52ddeba2a68388b544f529d2d92104420f77b0 (patch) | |
| tree | 15ddd47457a2cb4a96060747437d36474e4f6b4e /node_modules/bcp-47-match/readme.md | |
| parent | 53d6ae2b5568437afa5e4995580a3fb679b7b91b (diff) | |
Changed from static to 11ty!
Diffstat (limited to 'node_modules/bcp-47-match/readme.md')
| -rw-r--r-- | node_modules/bcp-47-match/readme.md | 315 |
1 files changed, 315 insertions, 0 deletions
diff --git a/node_modules/bcp-47-match/readme.md b/node_modules/bcp-47-match/readme.md new file mode 100644 index 0000000..c07c286 --- /dev/null +++ b/node_modules/bcp-47-match/readme.md @@ -0,0 +1,315 @@ +<!--lint disable no-html--> + +# bcp-47-match + +[![Build][build-badge]][build] +[![Coverage][coverage-badge]][coverage] +[![Downloads][downloads-badge]][downloads] +[![Size][size-badge]][size] + +Match BCP 47 language tags with language ranges per RFC 4647. + +## Contents + +* [What is this?](#what-is-this) +* [When should I use this?](#when-should-i-use-this) +* [Install](#install) +* [Use](#use) +* [API](#api) + * [`basicFilter(tags[, ranges='*'])`](#basicfiltertags-ranges) + * [`extendedFilter(tags[, ranges='*'])`](#extendedfiltertags-ranges) + * [`lookup(tags, ranges)`](#lookuptags-ranges) +* [Types](#types) +* [Compatibility](#compatibility) +* [Security](#security) +* [Related](#related) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package can match [BCP 47][spec] language tags with βlanguage rangesβ per +[RFC 4647][match]. +This is done by the `:lang()` pseudo class in CSS, the `Accept-Language` HTTP +header, and a few other places. + +## When should I use this? + +You can use this package if you want to choose a certain document based on +language tags. + +## Install + +This package is [ESM only][esm]. +In Node.js (version 14.14+, 16.0+), install with [npm][]: + +```sh +npm install bcp-47-match +``` + +In Deno with [`esm.sh`][esmsh]: + +```js +import * as bcp47Match from 'https://esm.sh/bcp-47-match@2' +``` + +In browsers with [`esm.sh`][esmsh]: + +```html +<script type="module"> + import * as bcp47Match from 'https://esm.sh/bcp-47-match@2?bundle' +</script> +``` + +## Use + +```js +import {basicFilter, extendedFilter, lookup} from 'bcp-47-match' + +const 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 identifier `basicFilter`, `extendedFilter`, and +`lookup`. +There is no default export. + +### `basicFilter(tags[, ranges='*'])` + +> π **Note**: See +> [Basic Filtering spec](https://tools.ietf.org/html/rfc4647#section-3.3.1) + +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. + +<details><summary>View matching table</summary> + +| 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` | βοΈ | | | | | | + +</details> + +###### Parameters + +* `tags` (`string` or `Array<string>`) + β list of BCP 47 tags +* `ranges` (`string` or `Array<string>`, default: `'*'`) + β list of RFC 4647 + [basic ranges][basic-range] + (aka, matching `/^(\*|[a-z]{1,8}(-[a-z0-9]{1,8})*)$/i`) + +###### Returns + +Possibly empty list of matching tags in the order they matched +(`Array<string>`). + +### `extendedFilter(tags[, ranges='*'])` + +> π **Note**: See +> [Extended Filtering spec](https://tools.ietf.org/html/rfc4647#section-3.3.2) + +Match language tags to a list of extended ranges. +Searches for matches between the first range and all tags, and continues +with further ranges. + +<details><summary>View matching table</summary> + +| 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` | βοΈ | | | | | | + +</details> + +###### Parameters + +* `tags` (`string` or `Array<string>`) + β list of BCP 47 tags +* `ranges` (`string` or `Array<string>`, default: `'*'`) + β list of RFC 4647 [extended ranges][extended-range] + (aka, matching `/^(\*|[a-z]{1,8})(-(\*|[a-z0-9]{1,8}))*$/i`) + +###### Returns + +Possibly empty list of matching tags in the order they matched +(`Array<string>`). + +### `lookup(tags, ranges)` + +> π **Note**: See +> [Lookup spec](https://tools.ietf.org/html/rfc4647#section-3.4) + +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. + +<details><summary>View matching table</summary> + +| 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` | | | | | | βοΈ | + +</details> + +###### 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 + +First matching tag in `tags`, `undefined` otherwise (`string?`). + +## Types + +This package is fully typed with [TypeScript][]. +It exports no additional types. + +## Compatibility + +This package is at least compatible with all maintained versions of Node.js. +As of now, that is Node.js 14.14+ and 16.0+. +It also works in Deno and modern browsers. + +## Security + +This package is safe. + +## Related + +* [`wooorm/bcp-47`](https://github.com/wooorm/bcp-47) + β parse and serialize BCP 47 language tags +* [`wooorm/bcp-47-normalize`](https://github.com/wooorm/bcp-47-normalize) + β normalize, canonicalize, and format BCP 47 tags +* [`wooorm/iso-3166`](https://github.com/wooorm/iso-3166) + β ISO 3166 codes +* [`wooorm/iso-639-2`](https://github.com/wooorm/iso-639-2) + β ISO 639-2 codes +* [`wooorm/iso-639-3`](https://github.com/wooorm/iso-639-3) + β ISO 639-3 codes +* [`wooorm/iso-15924`](https://github.com/wooorm/iso-15924) + β ISO 15924 codes +* [`wooorm/un-m49`](https://github.com/wooorm/un-m49) + β UN M49 codes + +## Contribute + +Yes please! +See [How to Contribute to Open Source][contribute]. + +## License + +[MIT][license] Β© [Titus Wormer][author] + +<!-- Definitions --> + +[build-badge]: https://github.com/wooorm/bcp-47-match/workflows/main/badge.svg + +[build]: https://github.com/wooorm/bcp-47-match/actions + +[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/bcp-47-match.svg + +[coverage]: https://codecov.io/github/wooorm/bcp-47-match + +[downloads-badge]: https://img.shields.io/npm/dm/bcp-47-match.svg + +[downloads]: https://www.npmjs.com/package/bcp-47-match + +[size-badge]: https://img.shields.io/bundlephobia/minzip/bcp-47-match.svg + +[size]: https://bundlephobia.com/result?p=bcp-47-match + +[npm]: https://docs.npmjs.com/cli/install + +[esmsh]: https://esm.sh + +[license]: license + +[author]: https://wooorm.com + +[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c + +[typescript]: https://www.typescriptlang.org + +[contribute]: https://opensource.guide/how-to-contribute/ + +[spec]: https://tools.ietf.org/html/bcp47 + +[match]: https://tools.ietf.org/html/rfc4647 + +[basic-range]: https://tools.ietf.org/html/rfc4647#section-2.1 + +[extended-range]: https://tools.ietf.org/html/rfc4647#section-2.2 |
