0
# i18n ISO Countries
1

2
i18n ISO Countries is a comprehensive internationalization library for ISO 3166-1 country codes, supporting 79 languages with complete bidirectional conversion between Alpha-2, Alpha-3, and Numeric country code formats. It provides localized country names and robust validation for international applications.
3

4
## Package Information
5

6
- **Package Name**: i18n-iso-countries
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install i18n-iso-countries`
10

11
## Core Imports
12

13
```javascript
14
// Node.js (all locales pre-loaded)
15
const countries = require("i18n-iso-countries");
16
```
17

18
```typescript
19
// TypeScript with Node.js
20
import * as countries from "i18n-iso-countries";
21
```
22

23
```javascript
24
// Browser (requires manual locale registration)
25
const countries = require("i18n-iso-countries");
26
countries.registerLocale(require("i18n-iso-countries/langs/en.json"));
27
countries.registerLocale(require("i18n-iso-countries/langs/fr.json"));
28
```
29

30
```typescript
31
// TypeScript with specific imports
32
import { getName, getAlpha2Code, registerLocale, Alpha2Code } from "i18n-iso-countries";
33
```
34

35
## Basic Usage
36

37
```javascript
38
const countries = require("i18n-iso-countries");
39

40
// Get country names
41
console.log(countries.getName("US", "en")); // "United States of America"
42
console.log(countries.getName("US", "de")); // "Vereinigte Staaten von Amerika"
43

44
// Convert between code formats
45
console.log(countries.alpha2ToAlpha3("US")); // "USA"
46
console.log(countries.alpha3ToNumeric("USA")); // "840"
47

48
// Get country code from name
49
console.log(countries.getAlpha2Code("Germany", "en")); // "DE"
50

51
// Validate codes
52
console.log(countries.isValid("US")); // true
53
console.log(countries.isValid("XX")); // false
54
```
55

56
## Architecture
57

58
i18n ISO Countries consists of several key components:
59

60
- **Code Conversion Engine**: Bidirectional mapping system between Alpha-2, Alpha-3, and Numeric codes
61
- **Localization System**: Support for 79 languages with country name translations
62
- **Environment Adaptation**: Different loading strategies for Node.js (auto-load all locales) vs Browser (selective loading)
63
- **Data Layer**: ISO 3166-1 compliant code mappings and multilingual country name databases
64
- **Validation System**: Comprehensive country code format validation and existence checking
65

66
## Capabilities
67

68
### Country Name Retrieval
69

70
Access localized country names with flexible selection options for official names, aliases, or all variants.
71

72
```javascript { .api }
73
function getName(
74
  code: string | number | Alpha2Code | Alpha3Code,
75
  lang: string,
76
  options?: { select: 'official' | 'alias' | 'all' }
77
): string | string[] | undefined;
78

79
function getNames(
80
  lang: string,
81
  options?: { select: 'official' | 'alias' | 'all' }
82
): LocalizedCountryNames<GetNameOptions>;
83
```
84

85
[Name Retrieval](./name-retrieval.md)
86

87
### Code Conversion
88

89
Convert between different country code formats including Alpha-2, Alpha-3, and Numeric codes with intelligent auto-detection.
90

91
```javascript { .api }
92
function alpha2ToAlpha3(alpha2: string): string | undefined;
93
function alpha3ToAlpha2(alpha3: string): string | undefined;
94
function toAlpha2(code: string | number | Alpha2Code | Alpha3Code): string | undefined;
95
function toAlpha3(code: string | number | Alpha2Code | Alpha3Code): string | undefined;
96
```
97

98
[Code Conversion](./code-conversion.md)
99

100
### Name to Code Conversion
101

102
Convert country names to country codes with support for both exact matching and diacritics-insensitive matching.
103

104
```javascript { .api }
105
function getAlpha2Code(name: string, lang: string): string | undefined;
106
function getAlpha3Code(name: string, lang: string): string | undefined;
107
function getSimpleAlpha2Code(name: string, lang: string): string | undefined;
108
function getSimpleAlpha3Code(name: string, lang: string): string | undefined;
109
```
110

111
[Name to Code Conversion](./name-to-code.md)
112

113
### Code Listings and Validation
114

115
Access complete mappings of country codes and validate country code formats and existence.
116

117
```javascript { .api }
118
function getAlpha2Codes(): { [alpha2Key: string]: string };
119
function getAlpha3Codes(): { [alpha3Key: string]: string };
120
function getNumericCodes(): { [numericKey: string]: string };
121
function isValid(code: string | number): boolean;
122
```
123

124
[Code Listings and Validation](./listings-validation.md)
125

126
### Locale Management
127

128
Register and manage language data for browser environments and query supported languages.
129

130
```javascript { .api }
131
function registerLocale(localeData: {
132
  locale: string;
133
  countries: { [alpha2Key: string]: string | string[] };
134
}): void;
135

136
function getSupportedLanguages(): string[];
137
function langs(): string[];
138
```
139

140
[Locale Management](./locale-management.md)
141

142
## Types
143

144
```typescript { .api }
145
interface GetNameOptions {
146
  select: 'all' | 'official' | 'alias';
147
}
148

149
type LocalizedCountryNames<T extends GetNameOptions> = {
150
  [alpha2Key: string]: CountryName<T>;
151
};
152

153
type CountryName<T extends GetNameOptions> = T extends { select: 'all' } 
154
  ? string[] 
155
  : string;
156

157
type LocaleData = {
158
  locale: string;
159
  countries: { [alpha2Key: string]: string[] | string };
160
};
161

162
type Alpha2Code = "AF" | "AL" | "DZ" | "AS" | "AD" | "AO" | "AI" | "AQ" | 
163
  "AG" | "AR" | "AM" | "AW" | "AU" | "AT" | "AZ" | "BS" | "BH" | "BD" | 
164
  "BB" | "BY" | "BE" | "BZ" | "BJ" | "BM" | "BT" | "BO" | "BA" | "BW" | 
165
  "BV" | "BR" | "IO" | "BN" | "BG" | "BF" | "BI" | "KH" | "CM" | "CA" | 
166
  "CV" | "KY" | "CF" | "TD" | "CL" | "CN" | "CX" | "CC" | "CO" | "KM" | 
167
  "CG" | "CD" | "CK" | "CR" | "CI" | "HR" | "CU" | "CY" | "CZ" | "DK" | 
168
  "DJ" | "DM" | "DO" | "EC" | "EG" | "SV" | "GQ" | "ER" | "EE" | "ET" | 
169
  "FK" | "FO" | "FJ" | "FI" | "FR" | "GF" | "PF" | "TF" | "GA" | "GM" | 
170
  "GE" | "DE" | "GH" | "GI" | "GR" | "GL" | "GD" | "GP" | "GU" | "GT" | 
171
  "GN" | "GW" | "GY" | "HT" | "HM" | "VA" | "HN" | "HK" | "HU" | "IS" | 
172
  "IN" | "ID" | "IR" | "IQ" | "IE" | "IL" | "IT" | "JM" | "JP" | "JO" | 
173
  "KZ" | "KE" | "KI" | "KP" | "KR" | "KW" | "KG" | "LA" | "LV" | "LB" | 
174
  "LS" | "LR" | "LY" | "LI" | "LT" | "LU" | "MO" | "MG" | "MW" | "MY" | 
175
  "MV" | "ML" | "MT" | "MH" | "MQ" | "MR" | "MU" | "YT" | "MX" | "FM" | 
176
  "MD" | "MC" | "MN" | "MS" | "MA" | "MZ" | "MM" | "NA" | "NR" | "NP" | 
177
  "NL" | "NC" | "NZ" | "NI" | "NE" | "NG" | "NU" | "NF" | "MP" | "MK" | 
178
  "NO" | "OM" | "PK" | "PW" | "PS" | "PA" | "PG" | "PY" | "PE" | "PH" | 
179
  "PN" | "PL" | "PT" | "PR" | "QA" | "RE" | "RO" | "RU" | "RW" | "SH" | 
180
  "KN" | "LC" | "PM" | "VC" | "WS" | "SM" | "ST" | "SA" | "SN" | "SC" | 
181
  "SL" | "SG" | "SK" | "SI" | "SB" | "SO" | "ZA" | "GS" | "ES" | "LK" | 
182
  "SD" | "SR" | "SJ" | "SZ" | "SE" | "CH" | "SY" | "TW" | "TJ" | "TZ" | 
183
  "TH" | "TL" | "TG" | "TK" | "TO" | "TT" | "TN" | "TR" | "TM" | "TC" | 
184
  "TV" | "UG" | "UA" | "AE" | "GB" | "US" | "UM" | "UY" | "UZ" | "VU" | 
185
  "VE" | "VN" | "VG" | "VI" | "WF" | "EH" | "YE" | "ZM" | "ZW" | "AX" | 
186
  "BQ" | "CW" | "GG" | "IM" | "JE" | "ME" | "BL" | "MF" | "RS" | "SX" | 
187
  "SS" | "XK";
188

189
type Alpha3Code = "AFG" | "ALB" | "DZA" | "ASM" | "AND" | "AGO" | "AIA" | 
190
  "ATA" | "ATG" | "ARG" | "ARM" | "ABW" | "AUS" | "AUT" | "AZE" | "BHS" | 
191
  "BHR" | "BGD" | "BRB" | "BLR" | "BEL" | "BLZ" | "BEN" | "BMU" | "BTN" | 
192
  "BOL" | "BIH" | "BWA" | "BVT" | "BRA" | "IOT" | "BRN" | "BGR" | "BFA" | 
193
  "BDI" | "KHM" | "CMR" | "CAN" | "CPV" | "CYM" | "CAF" | "TCD" | "CHL" | 
194
  "CHN" | "CXR" | "CCK" | "COL" | "COM" | "COG" | "COD" | "COK" | "CRI" | 
195
  "CIV" | "HRV" | "CUB" | "CYP" | "CZE" | "DNK" | "DJI" | "DMA" | "DOM" | 
196
  "ECU" | "EGY" | "SLV" | "GNQ" | "ERI" | "EST" | "ETH" | "FLK" | "FRO" | 
197
  "FJI" | "FIN" | "FRA" | "GUF" | "PYF" | "ATF" | "GAB" | "GMB" | "GEO" | 
198
  "DEU" | "GHA" | "GIB" | "GRC" | "GRL" | "GRD" | "GLP" | "GUM" | "GTM" | 
199
  "GIN" | "GNB" | "GUY" | "HTI" | "HMD" | "VAT" | "HND" | "HKG" | "HUN" | 
200
  "ISL" | "IND" | "IDN" | "IRN" | "IRQ" | "IRL" | "ISR" | "ITA" | "JAM" | 
201
  "JPN" | "JOR" | "KAZ" | "KEN" | "KIR" | "PRK" | "KOR" | "KWT" | "KGZ" | 
202
  "LAO" | "LVA" | "LBN" | "LSO" | "LBR" | "LBY" | "LIE" | "LTU" | "LUX" | 
203
  "MAC" | "MDG" | "MWI" | "MYS" | "MDV" | "MLI" | "MLT" | "MHL" | "MTQ" | 
204
  "MRT" | "MUS" | "MYT" | "MEX" | "FSM" | "MDA" | "MCO" | "MNG" | "MSR" | 
205
  "MAR" | "MOZ" | "MMR" | "NAM" | "NRU" | "NPL" | "NLD" | "NCL" | "NZL" | 
206
  "NIC" | "NER" | "NGA" | "NIU" | "NFK" | "MNP" | "MKD" | "NOR" | "OMN" | 
207
  "PAK" | "PLW" | "PSE" | "PAN" | "PNG" | "PRY" | "PER" | "PHL" | "PCN" | 
208
  "POL" | "PRT" | "PRI" | "QAT" | "REU" | "ROU" | "RUS" | "RWA" | "SHN" | 
209
  "KNA" | "LCA" | "SPM" | "VCT" | "WSM" | "SMR" | "STP" | "SAU" | "SEN" | 
210
  "SYC" | "SLE" | "SGP" | "SVK" | "SVN" | "SLB" | "SOM" | "ZAF" | "SGS" | 
211
  "ESP" | "LKA" | "SDN" | "SUR" | "SJM" | "SWZ" | "SWE" | "CHE" | "SYR" | 
212
  "TWN" | "TJK" | "TZA" | "THA" | "TLS" | "TGO" | "TKL" | "TON" | "TTO" | 
213
  "TUN" | "TUR" | "TKM" | "TCA" | "TUV" | "UGA" | "UKR" | "ARE" | "GBR" | 
214
  "USA" | "UMI" | "URY" | "UZB" | "VUT" | "VEN" | "VNM" | "VGB" | "VIR" | 
215
  "WLF" | "ESH" | "YEM" | "ZMB" | "ZWE" | "ALA" | "BES" | "CUW" | "GGY" | 
216
  "IMN" | "JEY" | "MNE" | "BLM" | "MAF" | "SRB" | "SXM" | "SSD" | "XKX";
217
```