is-language-code^5.2.2

No dependencies whatsoever. This package declares no dependencies or devDependencies.

Permalink to InstallationInstallation

Permalink to Quick TakeQuick Take

Permalink to ExamplesExamples

• Match registered tags without regard to letter case
• Explain a language tag containing two region subtags
• Explain an extended language subtag with the wrong prefix
• Validate an extended language subtag after its registered prefix
• Validate multiple uniquely prefixed extensions
• Accept an IANA-grandfathered language tag
• Reject text that does not resemble a language tag
• Validate a private-use language tag
• Explain why a repeated variant is invalid
• Validate language, script, region, and variant subtags together
• Explain an extension singleton without extension content
• Various examples

Purpose

is-language-code checks whether a value is a valid BCP 47 language tag. It follows RFC 5646 and validates registered subtags against the IANA Language Subtag Registry.

Language tags appear in places such as the HTML hreflang attribute:

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

A regular expression can check a tag’s broad shape, but it cannot confirm that each subtag is registered or appears in the right position. This package checks both. It also returns a human-readable reason when a value is invalid. For example, de-419-DE is invalid because it contains two region subtags.

API — isLangCode()

The main function isLangCode() is imported like this:

The function accepts one optional value:

function isLangCode(str?: unknown):
  | { res: true; message: null }
  | { res: false; message: string };

Pass the candidate language tag as str. An omitted value, a non-string value, or an empty string returns an invalid result instead of throwing.

The function returns a plain object:

isLangCode("zh-Hans-CN");
// => { res: true, message: null }

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

isLangCode(null);
// => { res: false, message: "Not a string given." }

Language tags are case-insensitive. Diagnostic messages normalize referenced subtags to lowercase, so en-US-POSIX produces:

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

Treat message as an explanation for people, not as a stable error code. Branch on res in application logic.

Deprecated language subtags

The IANA registry retains some deprecated language subtags for compatibility. They are valid inputs, but their preferred replacements should be used for new content:

This function validates tags; it does not rewrite a valid deprecated subtag to its preferred replacement.

API — version

You can import version:

Permalink to changelogChangelog