0
# Language Tags
1

2
A comprehensive JavaScript library for working with IANA language tags based on BCP 47 (RFC 5646) standards. This library enables validation, parsing, and manipulation of language tags and subtags with case-insensitive lookups and proper formatting according to RFC conventions.
3

4
## Package Information
5

6
- **Package Name**: language-tags
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES Modules)
9
- **Installation**: `npm install language-tags`
10
- **Minimum Node Version**: 22+
11

12
## Core Imports
13

14
```javascript
15
import { tags, check, subtags, filter, search, languages, language, region, type, types, date } from "language-tags";
16
```
17

18
For legacy CommonJS usage:
19

20
```javascript
21
const { tags, check, subtags, filter, search, languages, language, region, type, types, date } = require("language-tags");
22
```
23

24
Default import also provides access to all functions as properties (legacy support):
25

26
```javascript
27
import tags from "language-tags";
28

29
// All functions available as properties for backward compatibility
30
tags.check("en-US");           // same as check("en-US")
31
tags.search("French");         // same as search("French") 
32
tags.subtags("en");           // same as subtags("en")
33
tags.filter(["en", "xyz"]);   // same as filter(["en", "xyz"])
34
tags.languages("zh");         // same as languages("zh")
35
tags.language("en");          // same as language("en")
36
tags.region("US");            // same as region("US")
37
tags.type("en", "language");  // same as type("en", "language")
38
tags.types("en");             // same as types("en")
39
tags.date();                  // same as date()
40

41
// Note: Legacy property access is planned for removal in v3
42
```
43

44
## Basic Usage
45

46
```javascript
47
import { tags, check, search } from "language-tags";
48

49
// Validate a language tag
50
const isValid = check("en-US");
51
console.log(isValid); // true
52

53
// Get detailed tag information
54
const tag = tags("en-US");
55
console.log(tag.valid()); // true
56
console.log(tag.language().descriptions()); // ["English"]
57
console.log(tag.region().descriptions()); // ["United States"]
58

59
// Search for tags by description
60
const results = search("French");
61
console.log(results[0].subtag); // "fr"
62
```
63

64
## Architecture
65

66
The language-tags library is built around several key components:
67

68
- **Validation Functions**: Core functions (`tags`, `check`) for validating language tags against BCP 47 standards
69
- **Lookup Functions**: Utilities (`subtags`, `search`, `languages`) for finding and filtering language subtags
70
- **Tag Class**: Comprehensive class representing a complete language tag with validation and formatting
71
- **Subtag Class**: Individual subtag representation with type-specific functionality
72
- **Registry Data**: Integration with IANA language subtag registry for up-to-date standards compliance
73

74
## Capabilities
75

76
### Tag Validation
77

78
Core functionality for validating and working with complete language tags. Provides comprehensive validation against BCP 47 standards with detailed error reporting.
79

80
```javascript { .api }
81
function tags(tag: string): Tag;
82
function check(tag: string): boolean;
83
```
84

85
[Tag Operations](./tag-operations.md)
86

87
### Subtag Management
88

89
Utilities for working with individual language subtags including lookup, filtering, and type checking. Essential for analyzing tag components and building valid tags.
90

91
```javascript { .api }
92
function subtags(subtag: string | string[]): Subtag[];
93
function filter(subtags: string[]): string[];
94
function types(subtag: string): string[];
95
```
96

97
[Subtag Operations](./subtag-operations.md)
98

99
### Search and Discovery
100

101
Advanced search functionality for finding tags and subtags by description with support for regular expressions and case-insensitive matching.
102

103
```javascript { .api }
104
function search(query: string | RegExp, all?: boolean): (Tag | Subtag)[];
105
function languages(macrolanguage: string): Subtag[];
106
function language(subtag: string): Subtag | null;
107
function region(subtag: string): Subtag | null;
108
function type(subtag: string, type: string): Subtag | null;
109
```
110

111
[Search and Discovery](./search-discovery.md)
112

113
### Registry Information
114

115
Access to metadata about the underlying IANA language subtag registry.
116

117
```javascript { .api }
118
function date(): string;
119
```
120

121
## Types
122

123
```javascript { .api }
124
class Tag {
125
  constructor(tag: string);
126
  
127
  // Validation
128
  valid(): boolean;
129
  errors(): Error[];
130
  
131
  // Component access
132
  subtags(): Subtag[];
133
  language(): Subtag | null;
134
  region(): Subtag | null;
135
  script(): Subtag | null;
136
  find(type: string): Subtag | null;
137
  
138
  // Information
139
  type(): string;
140
  descriptions(): string[];
141
  preferred(): Tag | null;
142
  deprecated(): string | null;
143
  added(): string | undefined;
144
  
145
  // Formatting
146
  format(): string;
147
  
148
  // Error constants
149
  static ERR_DEPRECATED: number;
150
  static ERR_NO_LANGUAGE: number;
151
  static ERR_UNKNOWN: number;
152
  static ERR_TOO_LONG: number;
153
  static ERR_EXTRA_REGION: number;
154
  static ERR_EXTRA_EXTLANG: number;
155
  static ERR_EXTRA_SCRIPT: number;
156
  static ERR_DUPLICATE_VARIANT: number;
157
  static ERR_WRONG_ORDER: number;
158
  static ERR_SUPPRESS_SCRIPT: number;
159
  static ERR_SUBTAG_DEPRECATED: number;
160
  static ERR_EXTRA_LANGUAGE: number;
161
}
162

163
class Subtag {
164
  constructor(subtag: string, type: string);
165
  
166
  // Information
167
  type(): string;
168
  descriptions(): string[];
169
  preferred(): Subtag | null;
170
  deprecated(): string | null;
171
  added(): string | undefined;
172
  comments(): string[];
173
  scope(): string | null;
174
  script(): Subtag | null;
175
  
176
  // Formatting
177
  format(): string;
178
  toString(): string;
179
  
180
  // Error constants
181
  static ERR_NONEXISTENT: number;
182
  static ERR_TAG: number;
183
}
184
```