{"id":14462,"library":"bcp47","title":"BCP 47 Language Tag Parser","description":"The `bcp47` package provides a parser for BCP 47 language tags, a critical standard used in internationalization (i18n) for identifying human languages. The current stable version is `1.2.0`, with a rapid succession of recent releases in April 2026, indicating active development or a recent relaunch. This library's core function is to parse a BCP 47 tag and return a structured object containing all extracted components, or `null` if the tag is syntactically invalid, which acts as an implicit validation mechanism. Its key differentiator lies in its focused adherence to the BCP 47 specification, offering a lightweight and precise tool for tasks like content negotiation, managing localization resources, or configuring user interface languages. Unlike broader i18n frameworks, `bcp47` provides a dedicated, minimalist solution for this specific parsing requirement.","status":"active","version":"1.1.2","language":"javascript","source_language":"en","source_url":"git://github.com/gagle/node-bcp47","tags":["javascript","bcp47","parser","internationalization","i18n","language","locale"],"install":[{"cmd":"npm install bcp47","lang":"bash","label":"npm"},{"cmd":"yarn add bcp47","lang":"bash","label":"yarn"},{"cmd":"pnpm add bcp47","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `parse` function is a named export for ESM. It does not export a default.","wrong":"import bcp47 from 'bcp47'; bcp47.parse(...);","symbol":"parse","correct":"import { parse } from 'bcp47';"},{"note":"The `stringify` function is also a named export, complementing `parse` for reconstructing tags.","wrong":"const stringify = require('bcp47').stringify;","symbol":"stringify","correct":"import { stringify } from 'bcp47';"},{"note":"CommonJS users should prefer destructuring for named exports like `parse`.","wrong":"const bcp47 = require('bcp47'); const result = bcp47.parse('en-US');","symbol":"parse (CommonJS)","correct":"const { parse } = require('bcp47');"}],"quickstart":{"code":"import { parse, stringify } from 'bcp47';\n\n// Example 1: Parsing a valid language tag\nconst tag1 = 'en-US-u-attr-value';\nconst parsedTag1 = parse(tag1);\nconsole.log('Parsed Tag 1:', parsedTag1);\n// Expected output: { language: 'en', extlangs: [], script: null, region: 'US', variants: [], extensions: [{ singleton: 'u', privateuse: 'attr-value' }], privateuse: null }\n\n// Example 2: Parsing an invalid language tag\nconst tag2 = 'invalid-tag-$$';\nconst parsedTag2 = parse(tag2);\nconsole.log('Parsed Tag 2 (invalid):', parsedTag2);\n// Expected output: null\n\n// Example 3: Parsing a tag with script and variant\nconst tag3 = 'zh-Hans-SG-pinyin';\nconst parsedTag3 = parse(tag3);\nconsole.log('Parsed Tag 3:', parsedTag3);\n\n// Example 4: Stringifying a parsed object back to a tag\nif (parsedTag3) {\n  const rebuiltTag = stringify(parsedTag3);\n  console.log('Rebuilt Tag 3:', rebuiltTag);\n}\n","lang":"javascript","description":"Demonstrates parsing valid and invalid BCP 47 language tags, showing the structured output and the `null` return for invalid input. Also includes stringification."},"warnings":[{"fix":"Always check the return value of `parse()`: `const result = parse(tag); if (result) { /* use result */ } else { /* handle invalid tag */ }`","message":"The `parse` function returns `null` for any input that does not conform to the BCP 47 specification. This includes malformed tags, empty strings, or non-string inputs. Developers must explicitly check for `null` to avoid runtime errors when accessing properties of the parsed object.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"No direct fix for usage, but be mindful of the potential discrepancy between listed engine requirements and actual modern development practices. Test thoroughly on your target Node.js version.","message":"The package specifies `\"engines\": { \"node\": \">=0.10\" }`, indicating compatibility with extremely old Node.js versions. While this might suggest broad compatibility, modern applications should be aware that the code may not leverage contemporary JavaScript features or optimizations. However, given recent releases (April 2026), it's more likely a legacy `package.json` entry or the project has been significantly updated recently.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure the result of `parse()` is not `null` before attempting to access its properties. For example: `const parsed = parse(tag); if (parsed) { console.log(parsed.language); } else { console.error('Invalid BCP 47 tag'); }`","cause":"Attempting to access properties of the object returned by `parse()` without checking if the tag was valid, leading to an attempt to access properties on `null`.","error":"TypeError: Cannot read properties of null (reading 'language')"},{"fix":"Always ensure the input to `parse()` is a string. Validate the input type before calling `parse()`: `if (typeof tag === 'string') { parse(tag); } else { /* handle invalid input type */ }`","cause":"Passing a non-string value (e.g., `null`, `undefined`, a number, or an object) to the `parse()` function, which expects a string.","error":"TypeError: tag.toLowerCase is not a function"}],"ecosystem":"npm"}