BCP47 Helper

A lightweight TypeScript library for working with BCP 47 language tags in Node.js and browser environments. This library provides utilities to map, validate, search, and group language codes, making it easier to handle internationalization (i18n) tasks in your applications.

Note: The results of all functions depend on the data file located at `src/data/bcp47

-languages.json`. This file currently includes the most common languages and will be enhanced over time with additional languages and details.

Features

• Map Language Codes: Convert BCP 47 codes to their full names.
• Retrieve Language Info: Get detailed information (code, full name, language, region, description) for a specific language code.
• Find Language Variants: List all variants for a base language code.
• List All Languages: Retrieve a complete list of supported language codes with their full names.
• Search by Name: Search languages by full name, language, or region (case-insensitive).
• Group by Language: Organize language codes by their base language.
• Validate Codes: Check if a language code exists in the dataset.
• TypeScript Support: Fully typed with TypeScript for better developer experience.
• Lightweight: Optimized for both Node.js and browser environments.

Installation

Install the package via npm:

npm install bcp47-helper

Or via Yarn:

yarn add bcp47-helper

Usage

Importing the Library

import {
  mapLanguages,
  getLanguageInfo,
  getAvailableVariants,
  listAllLanguages,
  searchByName,
  groupByLanguage,
  validateCode
} from 'bcp47-helper';

Examples

1. Map Language Codes to Full Names

const codes = ['en-US', 'es-ES', 'fr-CA'];
const mapped = mapLanguages(codes);
console.log(mapped);
// Output: {
//   'en-US': 'English (United States)',
//   'es-ES': 'Spanish (Spain)',
//   'fr-CA': 'French (Canada)'
// }

2. Get Language Information

const info = getLanguageInfo('en-GB');
console.log(info);
// Output: {
//   code: 'en-GB',
//   fullName: 'English (United Kingdom)',
//   language: 'English',
//   region: 'United Kingdom',
//   description: 'English as spoken in the United Kingdom'
// }

3. Get Variants for a Base Language

const variants = getAvailableVariants('en');
console.log(variants);
// Output: {
//   'en-US': 'English (United States)',
//   'en-GB': 'English (United Kingdom)',
//   'en-AU': 'English (Australia)',
//   ...
// }

4. List All Languages

const allLanguages = listAllLanguages();
console.log(allLanguages);
// Output: {
//   'en-US': 'English (United States)',
//   'es-ES': 'Spanish (Spain)',
//   ...
// }

5. Search by Name or Region

const results = searchByName('spanish');
console.log(results);
// Output: {
//   'es-ES': 'Spanish (Spain)',
//   'es-MX': 'Spanish (Mexico)',
//   ...
// }

6. Group by Base Language

const grouped = groupByLanguage();
console.log(grouped);
// Output: {
//   'en': ['en-US', 'en-GB', 'en-AU', ...],
//   'es': ['es-ES', 'es-MX', ...],
//   ...
// }

7. Validate a Language Code

console.log(validateCode('en-US')); // true
console.log(validateCode('xx-XX')); // false

API Reference

mapLanguages(codes: string[]): Record<string, string>

Maps an array of BCP 47 language codes to their full names.

getLanguageInfo(code: string): LangInfo | null

Returns detailed information for a given language code or null if not found.

getAvailableVariants(baseLangs: string[] | string): Record<string, string>

Returns all variants for one or more base language codes.

listAllLanguages(): Record<string, string>

Returns all supported language codes with their full names.

searchByName(term: string): Record<string, string>

Searches languages by full name, language, or region (case-insensitive).

groupByLanguage(): Record<string, string[]>

Groups language codes by their base language.

validateCode(code: string): boolean

Validates if a language code exists in the dataset.

Type Definitions

export type LangInfo = {
  code: string;
  fullName: string;
  language: string;
  region: string;
  description: string;
};

Development

To contribute or modify the library:

1. Clone the repository:

git clone https://github.com/aumit/BCP-47-Helper.git

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Run in development mode with watch:

npm run dev

License

This project is licensed under the MIT License.

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

Issues

If you encounter any issues or have feature requests, please file them on the GitHub Issues page.

Author

• Aumit (GitHub)

Keywords

BCP 47, language tags, internationalization, i18n, TypeScript, JavaScript, language codes, locale, Node.js, browser