is-language-code^3.0.14

Is given string a language code (as per IANA)

Try it in a playground

Open

Install via npm

npm i is-language-code

Consume via a require():

const { isLangCode } = require("is-language-code");

or as an ES Module:

import { isLangCode } from "is-language-code";

Install as a script, via CDN

Put this in your HTML:

<script src="https://cdn.jsdelivr.net/npm/is-language-code/dist/is-language-code.umd.js"></script>

Then, you’ll get a global variable isLanguageCode in your Global object and you consume it like this:

const { isLangCode } = isLanguageCode;

Trivia

This program has 813 assertions in its unit tests. That's more than all unit test assertions' median (44) and more than geometric mean (72).

In monorepo, one other package, emlint, consumes this package.

§ Quick Take

import { strict as assert } from "assert";
import { isLangCode } from "is-language-code";

assert.deepEqual(isLangCode("de-419-DE"), {
  res: false,
  message: 'Two region subtags, "419" and "de".',
});

assert.deepEqual(isLangCode("sr-Latn"), {
  res: true,
  message: null,
});

⬆ back to top

§ Examples

program example: Various examples

⬆ back to top

§ Purpose

This program tells, is a given string a valid language tag.

It is based on RFC #5646 "Tags for Identifying Languages" which was released in 2009 and as of Jan 2020 it is still current .

Language tags are used in many places, for example, in HTML attribute hreflang:

<link rel="alternate" href="http://example.com" hreflang="es-es" />

It's impossible to properly match the spec using regex only - you can validate that allowed characters are in allowed places but you can't validate the meaning those characters have. The position of subtag and arrangement matters. Also, this program returns explanations why it deemed the input not to be a language tag.

For example, de-419-DE is wrong because it contains two region tags, 419 and DE.

Existing regex-based solutions like ietf-language-tag-regex don't have much of a logic besides enforcing subtag order and subtag length, for example, it reports any string, longer than two characters, as a valid language tag. We, on other hand, validate each value against known IANA-registered names.

⬆ back to top

§ API

isLangCode([str])

In other words, a function which takes a string.

Theoretically, input string is optional — if the input is not a string or an empty string, a negative answer will be returned. The program is liberal and doesn't throw errors.

Returns a plain object:

Key's name	Key value's type	Description
`res`	boolean	Answers, is this valid language code
`message`	`null` or string	Explains what's wrong if answer is negative

For example,

{
  res: false,
  message: `Unrecognised language subtag, "posix".`
}

{
  res: true,
  message: null
}

Non-string or empty-string inputs always yield false, program does not throw.

Language tags are not case-sensitive (there exist conventions for the capitalization of some of the subtags but they don't carry meaning). For performance reasons, all references of the input uses lowercase, even if you entered in uppercase. For example, en-US-POSIX would get reported as lowercase "posix":

{
  res: false,
  message: `Unrecognised language subtag, "posix".`
}

⬆ back to top

§ By the way

Back in 1989, code iw was replaced with he so we won't include iw. Similar way, ji and in are not included.

The following codes have been added in 1989 (nothing later): ug (Uigur), iu (Inuktitut, also called Eskimo), za (Zhuang), he (Hebrew, replacing iw), yi (Yiddish, replacing ji), and id (Indonesian, replacing in). — https://www.ietf.org/rfc/rfc1766.txt

⬆ back to top