# i18n-iso-countries

> i18n for ISO 3166-1 country codes

Latest version **7.14.0** (published 2025-02-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install i18n-iso-countries
pnpm add i18n-iso-countries
yarn add i18n-iso-countries
bun add i18n-iso-countries
```

## Health

**Score 35/100 (D)** — status: maintenance-mode.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 7.14.0 |
| Published | 2025-02-17 |
| First published | 2013-12-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >= 12 |
| Dependencies | 1 |
| Unpacked size | 609.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 904 |
| Author | Andreas Wittig |
| Maintainers | hellomichibye, andreaswittig |
| Keywords | i18n, iso, 3166, iso 3166, iso 3166-1, alpha, alpha-2, alpha-3, numeric, country, countries, af, am, ar, az, be, bg, bn, br, bs, ca, cs, cy, da, de, dv, el, en, es, et, eu, fa, fi, fr, ga, gl, ha, he, hi, hr, hu, hy, id, is, it, ja, ka, kk, km, ko, ku, ky, lt, lv, mk, ml, mn, mr, ms, mt, nb, nl, nn, no, pl, ps, pt, ro, ru, sd, sk, sl, so, sq, sr, sv, sw, ta, tg, th, tk, tr, tt, uk, ug, ur, uz, vi, zh |

## Links

- npm: https://www.npmjs.com/package/i18n-iso-countries
- Repository: https://github.com/michaelwittig/node-i18n-iso-countries
- Homepage: https://github.com/michaelwittig/node-i18n-iso-countries#readme
- Issues: https://github.com/michaelwittig/node-i18n-iso-countries/issues
- npm.io page: https://npm.io/package/i18n-iso-countries

## Dependencies (1)

- [diacritics](https://npm.io/package/diacritics.md) 1.3.0

## Alternatives

- [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads
- [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads
- [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads
- [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads
- [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads

## Recent versions

- 7.14.0 (latest) — 2025-02-17
- 7.13.0 — 2024-11-07
- 7.12.0 — 2024-09-09
- 7.11.3 — 2024-07-18
- 7.11.2 — 2024-05-13
- 7.11.1 — 2024-04-24
- 7.11.0 — 2024-03-21
- 7.10.1 — 2024-03-04
- 7.10.0 — 2024-02-06
- 7.9.0 — 2024-02-03
- 7.8.0 — 2024-01-22
- 7.7.0 — 2023-09-14
- 7.6.0 — 2023-04-12
- 7.5.0 — 2022-06-23
- 7.4.0 — 2022-03-22
- … 97 more at https://npm.io/package/i18n-iso-countries/versions

## README

# i18n-iso-countries

i18n for ISO 3166-1 country codes. We support Alpha-2, Alpha-3 and Numeric codes from ['Wikipedia: Officially assigned code elements'][iso:3166-1]

## Installing

Install it using npm: `npm install i18n-iso-countries`

```javascript
var countries = require("i18n-iso-countries");
```

If you use `i18n-iso-countries` with Node.js, you are done. If you use the package in a browser environment, you have to register the languages you want to use to minimize the file size.

```javascript
// Support french & english languages.
countries.registerLocale(require("i18n-iso-countries/langs/en.json"));
countries.registerLocale(require("i18n-iso-countries/langs/fr.json"));
```

## Code to Country

### Get the name of a country by its ISO 3166-1 Alpha-2, Alpha-3 or Numeric code

```javascript
var countries = require("i18n-iso-countries");
// in a browser environment: countries.registerLocale(require("i18n-iso-countries/langs/en.json"));
console.log("US (Alpha-2) => " + countries.getName("US", "en")); // United States of America
console.log("US (Alpha-2) => " + countries.getName("US", "de")); // Vereinigte Staaten von Amerika
console.log("USA (Alpha-3) => " + countries.getName("USA", "en")); // United States of America
console.log("USA (Numeric) => " + countries.getName("840", "en")); // United States of America
```

#### Get aliases/short name using select

```javascript
// Some countries have alias/short names defined. `select` is used to control which
// name will be returned.
console.log("GB (select: official) => " + countries.getName("GB", "en", {select: "official"})); // United Kingdom
console.log("GB (select: alias) => " + countries.getName("GB", "en", {select: "alias"})); // UK
console.log("GB (select: all) => " + countries.getName("GB", "en", {select: "all"})); // ["United Kingdom", "UK", "Great Britain"]
// Countries without an alias will always return the offical name
console.log("LT (select: official) => " + countries.getName("LT", "en", {select: "official"})); // Lithuania
console.log("LT (select: alias) => " + countries.getName("LT", "en", {select: "alias"})); // Lithuania
console.log("LT (select: all) => " + countries.getName("LT", "en", {select: "all"})); // ["Lithuania"]
```

### Get all names by their ISO 3166-1 Alpha-2 code

```javascript
var countries = require("i18n-iso-countries");
// in a browser environment: countries.registerLocale(require("i18n-iso-countries/langs/en.json"));
console.log(countries.getNames("en", {select: "official"})); // { 'AF': 'Afghanistan', 'AL': 'Albania', [...], 'ZM': 'Zambia', 'ZW': 'Zimbabwe' }
```

### Supported languages (ISO 639-1)

> In case you want to add new language, please refer [ISO 639-1 table][iso:639-1].

- `af`: Afrikaans
- `am`: Amharic
- `ar`: Arabic
- `az`: Azerbaijani
- `be`: Belorussian
- `bg`: Bulgarian
- `bn`: Bengali
- `br`: Breton
- `bs`: Bosnian
- `ca`: Catalan
- `cs`: Czech
- `cy`: Cymraeg
- `da`: Danish
- `de`: German
- `dv`: Dhivehi
- `en`: English
- `es`: Spanish
- `et`: Estonian
- `eu`: Basque
- `fa`: Persian
- `fi`: Finnish
- `fr`: French
- `ga`: Irish
- `gl`: Galician
- `el`: Greek
- `ha`: Hausa
- `he`: Hebrew
- `hi`: Hindi
- `hr`: Croatian
- `hu`: Hungarian
- `hy`: Armenian
- `is`: Icelandic
- `it`: Italian
- `id`: Indonesian
- `ja`: Japanese
- `ka`: Georgian
- `kk`: Kazakh
- `km`: Khmer
- `ko`: Korean
- `ku`: Kurdish
- `ky`: Kyrgyz
- `lt`: Lithuanian
- `lv`: Latvian
- `mk`: Macedonian
- `ml`: Malayalam
- `mn`: Mongolian
- `mr`: Marathi
- `ms`: Malay
- `mt`: Maltese
- `nb`: Norwegian Bokmål
- `nl`: Dutch
- `nn`: Norwegian Nynorsk
- `no`: Norwegian
- `pl`: Polish
- `ps`: Pashto
- `pt`: Portuguese
- `ro`: Romanian
- `ru`: Russian
- `sd`: Sindhi
- `sk`: Slovak
- `sl`: Slovene
- `so`: Somali
- `sq`: Albanian
- `sr`: Serbian
- `sv`: Swedish
- `sw`: Swahili
- `ta`: Tamil
- `tg`: Tajik
- `th`: Thai
- `tk`: Turkmen
- `tr`: Turkish
- `tt`: Tatar
- `ug`: Uyghur
- `uk`: Ukrainian
- `ur`: Urdu
- `uz`: Uzbek
- `zh`: Chinese
- `vi`: Vietnamese

[List of ISO 639-1 codes](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)

### Get all supported languages (ISO 639-1)

```javascript
var countries = require("i18n-iso-countries");
console.log("List of supported languages => " + countries.getSupportedLanguages());
// List of supported languages => ["cy", "dv", "sw", "eu", "af", "am", ...]
```

### Country to Code

```javascript
var countries = require("i18n-iso-countries");
// in a browser environment: countries.registerLocale(require("i18n-iso-countries/langs/en.json"));
console.log("United States of America => " + countries.getAlpha2Code("United States of America", "en"));
// United States of America => US

console.log("United States of America => " + countries.getAlpha3Code("United States of America", "en"));
// United States of America => USA
```

## Codes

### Convert Alpha-3 to Alpha-2 code

```javascript
var countries = require("i18n-iso-countries");
// in a browser environment: countries.registerLocale(require("i18n-iso-countries/langs/en.json"));
console.log("USA (Alpha-3) => " + countries.alpha3ToAlpha2("USA") + " (Alpha-2)");
// USA (Alpha-3) => US (Alpha-2)
```

### Convert Numeric to Alpha-2 code

```javascript
var countries = require("i18n-iso-countries");
// in a browser environment: countries.registerLocale(require("i18n-iso-countries/langs/en.json"));
console.log("840 (Numeric) => " + countries.numericToAlpha2("840") + " (Alpha-2)");
// 840 (Numeric) => US (Alpha-2)
```

### Convert Alpha-2 to Alpha-3 code

```javascript
var countries = require("i18n-iso-countries");
// in a browser environment: countries.registerLocale(require("i18n-iso-countries/langs/en.json"));
console.log("DE (Alpha-2) => " + countries.alpha2ToAlpha3("DE") + " (Alpha-3)");
// DE (Alpha-2) => DEU (Alpha-3)
```

### Convert Numeric to Alpha-3 code

```javascript
var countries = require("i18n-iso-countries");
// in a browser environment: countries.registerLocale(require("i18n-iso-countries/langs/en.json"));
console.log("840 (Numeric) => " + countries.numericToAlpha3("840") + " (Alpha-3)");
// 840 (Numeric) => USA (Alpha-3)
```

### Convert Alpha-3 to Numeric code

```javascript
var countries = require("i18n-iso-countries");
// in a browser environment: countries.registerLocale(require("i18n-iso-countries/langs/en.json"));
console.log(countries.alpha3ToNumeric("SWE"));
// 752
```

### Convert Alpha-2 to Numeric code

```javascript
var countries = require("i18n-iso-countries");
// in a browser environment: countries.registerLocale(require("i18n-iso-countries/langs/en.json"));
console.log(countries.alpha2ToNumeric("SE"));
// 752
```

### Get all Alpha-2 codes

```javascript
var countries = require("i18n-iso-countries");
// in a browser environment: countries.registerLocale(require("i18n-iso-countries/langs/en.json"));
console.log(countries.getAlpha2Codes());
// { 'AF': 'AFG', 'AX': 'ALA', [...], 'ZM': 'ZMB', 'ZW': 'ZWE' }
```

### Get all Alpha-3 codes

```javascript
var countries = require("i18n-iso-countries");
// in a browser environment: countries.registerLocale(require("i18n-iso-countries/langs/en.json"));
console.log(countries.getAlpha3Codes());
// { 'AFG': 'AF', 'ALA': 'AX', [...], 'ZMB': 'ZM', 'ZWE': 'ZW' }
```

### Get all Numeric codes

```javascript
var countries = require("i18n-iso-countries");
// in a browser environment: countries.registerLocale(require("i18n-iso-countries/langs/en.json"));
console.log(countries.getNumericCodes());
// { '004': 'AF', '008': 'AL', [...], '887': 'YE', '894': 'ZM' }
```

### Validate country code

```javascript
var countries = require("i18n-iso-countries");
// in a browser environment: countries.registerLocale(require("i18n-iso-countries/langs/en.json"));
console.log(
  countries.isValid("US"),
  countries.isValid("USA"),
  countries.isValid("XX")
);
// true, true, false
```

## Contribution

To add a language:

- add a json file under [langs/](langs)
- add the language to the list in supportedLocales.json at the top
- add language to section **Supported languages** in [README.md](#supported-languages-iso-639-1)
- add language to keywords in [package.json](package.json)
- run `npm run lint` and `npm test`
- open a PR on GitHub

You can check codes here: https://www.iso.org/obp/ui/#home

[iso:639-1]: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
[iso:3166-1]: http://en.wikipedia.org/wiki/ISO_3166-1#Officially_assigned_code_elements

---
_Source: https://npm.io/package/i18n-iso-countries · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._