bcp47-helper/README.md

A lightweight TypeScript library for parsing, validating, and managing BCP 47 language tags in Node.js and browser environments.

# BCP47 Helper

A lightweight TypeScript library for working with [BCP 47 language tags](https://www.rfc-editor.org/info/bcp47) 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.

[![npm version](https://img.shields.io/npm/v/bcp47-helper.svg)](https://www.npmjs.com/package/bcp47-helper)
[![License](https://img.shields.io/npm/l/bcp47-helper.svg)](https://github.com/aumit/BCP-47-Helper/blob/main/LICENSE)
[![Build Status](https://img.shields.io/github/workflow/status/aumit/BCP-47-Helper/CI)](https://github.com/aumit/BCP-47-Helper/actions)

## 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:

```bash
npm install bcp47-helper
```

Or via Yarn:

```bash
yarn add bcp47-helper
```

## Usage

### Importing the Library

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

### Examples

#### 1. Map Language Codes to Full Names

```javascript
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

```javascript
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

```javascript
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

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

#### 5. Search by Name or Region

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

#### 6. Group by Base Language

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

#### 7. Validate a Language Code

```javascript
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

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

## Development

To contribute or modify the library:

1. Clone the repository:

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

2. Install dependencies:

```bash
npm install
```

3. Build the project:

```bash
npm run build
```

4. Run in development mode with watch:

```bash
npm run dev
```

## License

This project is licensed under the [MIT License](LICENSE).

## Contributing

Contributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/aumit/BCP-47-Helper).

## Issues

If you encounter any issues or have feature requests, please file them on the [GitHub Issues page](https://github.com/aumit/BCP-47-Helper/issues).

## Author

- Aumit ([GitHub](https://github.com/aumit))

## Keywords

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