ally-bcp-47

A comprehensive TypeScript library for validating, parsing, and working with BCP-47 language tags according to RFC 5646.

Links

• npm package
• GitHub repository

Features

• Complete BCP-47 syntax validation - Validates against the full ABNF grammar
• Detailed parsing - Breaks down language tags into their component subtags
• Helpful error messages - Clear, actionable error reporting
• No dependencies - Lightweight and focused
• TypeScript-first - Full type definitions included

Installation

1npm install @aleksejdix/ally-bcp47

Usage

Basic Validation

1import { isValid, isWellFormed } from "@aleksejdix/ally-bcp47";
2
3// Check if a tag is well-formed (syntax only)
4isWellFormed("en-US"); // true
5isWellFormed("en--US"); // false
6
7// Check if a tag is valid (syntax + registry validation)
8isValid("en-US"); // true
9isValid("xy-ZZ"); // false (invalid subtags)

Detailed Validation

1import { validateLanguageTag } from "@aleksejdix/ally-bcp47";
2
3const result = validateLanguageTag("en-US");
4console.log(result);
5/* Output:
6{
7  isWellFormed: true,
8  isValid: true,
9  tag: {
10    tag: "en-us",
11    language: "en",
12    region: "us"
13  }
14}
15*/
16
17const invalidResult = validateLanguageTag("en-a");
18console.log(invalidResult);
19/* Output:
20{
21  isWellFormed: false,
22  isValid: false,
23  errors: [{
24    type: "invalid_extension",
25    message: "Extension singleton a must be followed by at least one extension subtag",
26    subtag: "a",
27    subtagType: "extension",
28    position: 3
29  }]
30}
31*/

Parsing Tags

1import { parseTag } from "@aleksejdix/ally-bcp47";
2
3const tag = parseTag("zh-Hans-CN-x-private");
4console.log(tag);
5/* Output:
6{
7  tag: "zh-hans-cn-x-private",
8  language: "zh",
9  script: "hans",
10  region: "cn",
11  privateuse: ["private"]
12}
13*/

Validation Options

The validateLanguageTag function accepts options to customize the validation:

1import { validateLanguageTag } from "@aleksejdix/ally-bcp47";
2
3validateLanguageTag("en-US", {
4  checkRegistry: true, // Whether to validate against the registry (default: true)
5  warnOnDeprecated: true, // Whether to return warnings for deprecated subtags (default: true)
6  warnOnRedundantScript: true, // Whether to warn about redundant scripts (default: true)
7});

Tag Components

The library breaks down language tags into their component parts:

• language - Primary language subtag (e.g., 'en', 'fr')
• extlang - Extended language subtags (e.g., 'cmn')
• script - Script subtag (e.g., 'Latn', 'Cyrl')
• region - Region subtag (e.g., 'US', '001')
• variants - Variant subtags (e.g., '1996')
• extensions - Extension subtags (e.g., 'u-ca-gregory')
• privateuse - Private use subtags (e.g., 'x-private')

Roadmap

• Registry validation
• Canonicalization
• Registry update mechanism
• More extensive validation options
• Tag generation from components

European Accessibility Act Compliance

This library includes comprehensive testing for all European language tags to support compliance with the European Accessibility Act (Directive (EU) 2019/882).

Features for EAA Compliance

• Validation of all 24 official EU language tags
• Support for regional and minority language tags
• Validation of accessibility-related extensions (number formatting, calendar systems, etc.)
• Specific handling of common errors like country codes used as language codes (e.g., ch-DE)

Running European-specific Tests

1# Test all European language tags
2npm run test:european
3
4# Test accessibility extensions
5npm run test:accessibility
6
7# Run the ch-DE specific test cases
8npm run test:ch-de
9
10# Demo of European language tag validation
11npm run demo:european

For more details, see the European Accessibility Act Compliance Documentation.

Americans with Disabilities Act (ADA) Compliance

This library includes comprehensive testing for US language tags to support compliance with the Americans with Disabilities Act (ADA) requirements for web accessibility.

Features for ADA Compliance

• Validation of US English and other common US language tags
• Support for languages commonly spoken in the US
• Validation of accessibility-related extensions (time formats, number systems, measurement units)
• Private use extensions for screen readers and assistive technologies
• Case normalization according to BCP-47 standards

Running ADA-specific Tests

1# Test all ADA-related language tags
2npm run test:ada
3
4# Demo of ADA-related language tag validation
5npm run demo:ada

For more details, see the Americans with Disabilities Act Compliance Documentation.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT