A BCP-47/IETF locale specifier parser/validator
npm install ilib-localeA BCP-47 locale specifier parser and validator. BCP-47 locale specifiers
are also known as IETF locale tags.
``sh`
npm install ilib-localeor
yarn add ilib-locale
Here is how you load ilib-locale:
`javascript
//ES5
var Locale = require("ilib-locale");
var l = new Locale("ja-JP");
//ES6
import Locale from "ilib-locale";
var l = new Locale("ja-JP");
`
Here is how you use ilib-locale to parse locale specifiers:
`javascript`
var l = new Locale("zh-Hans-CN");
console.log("Language: " + l.getLanguage()); // outputs "zh"
console.log("Script: " + l.getScript()); // outputs "Hans"
console.log("Region: " + l.getRegion()); // outputs "CN"
Full documentation: Locale class
To get the default locale of the platform, simply make a new Locale instance
without parameters.
`javascript
var locale = new Locale();
console.log("Current locale is " + locale.getSpec()); // output "Current locale is en-US" in the US
`
This module uses ilib-env to determine what the current platform is, and looksIntl
in the appropriate place for the locale specifier. For most modern browsers and
recent versions of nodejs, this comes from the object, which retrieves
the locale from the environment variables or operating system.
If you have the locale parts and would like to construct a locale specifier, pass the
parts to the constructor:
`javascript
var language = "sr";
var script = "Cyrl";
var region = "SR";
var variant = "u-sort-old";
var locale = new Locale(language, region, variant, script);
console.log("Locale spec is " + locale.getSpec()); // output "Locale spec is sr-Cyrl-SR-u-sort-old"
`
If you have a string and you would like to validate that it forms a valid BCP-47 tag,
you can use the isValid method to do that:
`javascript
var l = new Locale("mn-XM");
console.log("Locale is valid: " + l.isValid());
// output "Locale is valid: false" because XM is not a valid region code
`
In order for a locale spec to be valid, each of its parts needs to conform to the
codes in the ISO standard that governs that part:
- Language. Language codes must be one of the two- or
three- lower-case letter codes from the
ISO 639 standard.
- Script. Script codes must be one of the four letter codes from the
ISO 15924 standard.
- Region. Region codes must be one of the two upper-case letter codes from the
ISO 3166 alpha-2
standard or a 3 digit code from the UN M49
standard or the ISO 3166-1 numeric-3 standard.
BCP-47 defines extension subtags that allow for additional locale information
beyond the basic language, script, region, and variant. Extensions are introduced
by a single-letter singleton followed by one or more subtags.
The u extension is used for Unicode locale extensions such as collation order,
numbering system, and calendar type:
`javascript
var l = new Locale("de-DE-u-co-phonebk");
console.log("Language: " + l.getLanguage()); // outputs "de"
console.log("Region: " + l.getRegion()); // outputs "DE"
console.log("Variant: " + l.getVariant()); // outputs "u-co-phonebk"
var l2 = new Locale("zh-Hans-CN-u-nu-hanidec");
console.log("Language: " + l2.getLanguage()); // outputs "zh"
console.log("Script: " + l2.getScript()); // outputs "Hans"
console.log("Region: " + l2.getRegion()); // outputs "CN"
console.log("Variant: " + l2.getVariant()); // outputs "u-nu-hanidec"
`
The t extension indicates transformed content, such as transliterated text:
`javascript`
var l = new Locale("en-t-ja");
console.log("Language: " + l.getLanguage()); // outputs "en"
console.log("Variant: " + l.getVariant()); // outputs "t-ja"
The x singleton introduces private use subtags for custom locale extensions:
`javascript
var l = new Locale("en-x-pseudo");
console.log("Language: " + l.getLanguage()); // outputs "en"
console.log("Variant: " + l.getVariant()); // outputs "x-pseudo"
var l2 = new Locale("en-US-x-sort-phonebook");
console.log("Language: " + l2.getLanguage()); // outputs "en"
console.log("Region: " + l2.getRegion()); // outputs "US"
console.log("Variant: " + l2.getVariant()); // outputs "x-sort-phonebook"
`
This is useful for specifying custom locale variations such as pseudo-localization
(x-pseudo), custom sorting orders, or other application-specific locale extensions.
BCP-47 allows multiple variant subtags in a locale specifier. The parser preserves
all variants, concatenating them with hyphens:
`javascript`
var l = new Locale("sl-IT-nedis-rozaj");
console.log("Language: " + l.getLanguage()); // outputs "sl"
console.log("Region: " + l.getRegion()); // outputs "IT"
console.log("Variant: " + l.getVariant()); // outputs "nedis-rozaj"
Variants can also be combined with extension subtags:
`javascript``
var l = new Locale("ca-ES-valencia-u-co-trad");
console.log("Language: " + l.getLanguage()); // outputs "ca"
console.log("Region: " + l.getRegion()); // outputs "ES"
console.log("Variant: " + l.getVariant()); // outputs "valencia-u-co-trad"
Copyright © 2021-2025, JEDLSoft
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
See CHANGELOG.md