i18n-iso-countries

What is i18n-iso-countries?

The i18n-iso-countries npm package provides functionalities for working with ISO 3166-1 country codes. It allows you to get country names in different languages, convert between different country code formats, and validate country codes.

What are i18n-iso-countries's main functionalities?

Get Country Name by Alpha-2 Code

This feature allows you to get the name of a country given its Alpha-2 code. You can specify the language in which you want the country name.

const countries = require('i18n-iso-countries');
countries.registerLocale(require('i18n-iso-countries/langs/en.json'));
const countryName = countries.getName('US', 'en');
console.log(countryName); // Output: United States

Get Alpha-2 Code by Country Name

This feature allows you to get the Alpha-2 code of a country given its name. You can specify the language in which the country name is provided.

const countries = require('i18n-iso-countries');
countries.registerLocale(require('i18n-iso-countries/langs/en.json'));
const countryCode = countries.getAlpha2Code('United States', 'en');
console.log(countryCode); // Output: US

Validate Country Code

This feature allows you to validate whether a given country code is a valid ISO 3166-1 Alpha-2 code.

const countries = require('i18n-iso-countries');
const isValid = countries.isValid('US');
console.log(isValid); // Output: true

Get Country Names in All Languages

This feature allows you to get the names of all countries in a specified language.

const countries = require('i18n-iso-countries');
countries.registerLocale(require('i18n-iso-countries/langs/en.json'));
countries.registerLocale(require('i18n-iso-countries/langs/fr.json'));
const countryNames = countries.getNames('en');
console.log(countryNames); // Output: { 'AF': 'Afghanistan', 'AX': 'Åland Islands', ... }

Other packages similar to i18n-iso-countries

country-list

The country-list package provides a list of country names and their corresponding ISO 3166-1 Alpha-2 codes. It is simpler and more lightweight compared to i18n-iso-countries, but it does not support multiple languages or validation of country codes.

iso-3166-1

The iso-3166-1 package provides ISO 3166-1 country codes and names. It is similar to i18n-iso-countries but does not offer as extensive support for multiple languages and lacks some of the additional functionalities like validation.

countries-list

The countries-list package provides a comprehensive list of countries with their ISO 3166-1 codes, names, and additional information like currency and phone codes. It offers more detailed information compared to i18n-iso-countries but may be overkill if you only need basic country code and name functionalities.

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'

Installing

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

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.

// 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

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", {select: "official"})); // United States of America
console.log("US (Alpha-2) => " + countries.getName("US", "de", {select: "official"})); // Vereinigte Staaten von Amerika
console.log("USA (Alpha-3) => " + countries.getName("USA", "en", {select: "official"})); // United States of America
console.log("USA (Numeric) => " + countries.getName("840", "en", {select: "official"})); // United States of America

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

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.

• af: Afrikaans
• am: Amharic
• ar: Arabic
• az: Azerbaijani
• be: Belorussian
• bg: Bulgarian
• bn: Bengali
• 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
• 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
• ms: Malay
• 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
• tr: Turkish
• tt: Tatar
• ug: Uyghur
• uk: Ukrainian
• ur: Urdu
• uz: Uzbek
• zh: Chinese
• vi: Vietnamese

List of ISO 639-1 codes

Country to Code

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

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

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

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

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

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

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

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

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

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

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/
• add the language to the data object in entry-node.js at the top
• add language to section Supported languages in README.md
• add language to keywords in 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