i18n-iso-countries

Install the package using npm to get started with ISO 3166-1 country code internationalization.

npm install i18n-iso-countries

In Node.js, all locales are available by default. However, in a browser environment, you must manually register the specific languages you want to use to minimize the bundle size. You can find the language JSON files in the i18n-iso-countries/langs/ directory.

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

The library provides several methods to convert between Alpha-2, Alpha-3, and Numeric codes:

Alpha-2 Conversions:

• alpha3ToAlpha2(alpha3Code)
• numericToAlpha2(numericCode)

Alpha-3 Conversions:

• alpha2ToAlpha3(alpha2Code)
• numericToAlpha3(numericCode)
• alpha3ToNumeric(alpha3Code)

Numeric Conversions:

• alpha2ToNumeric(alpha2Code)
• alpha3ToNumeric(alpha3Code)

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

console.log(countries.alpha3ToAlpha2("USA")); // US
console.log(countries.numericToAlpha2("840")); // US
console.log(countries.alpha2ToAlpha3("DE")); // DEU
console.log(countries.numericToAlpha3("840")); // USA
console.log(countries.alpha3ToNumeric("SWE")); // 752
console.log(countries.alpha2ToNumeric("SE")); // 752

Use getSupportedLanguages() to return an array of all ISO 639-1 language codes currently supported by the library.

var countries = require("i18n-iso-countries");
console.log(countries.getSupportedLanguages());
// ["cy", "dv", "sw", "eu", "af", ...]

Use getNames(language, options) to retrieve a mapping of all Alpha-2 country codes to their names in the specified language. You can use the select option (official, alias, or all) to filter the names returned in the object values.

var countries = require("i18n-iso-countries");
console.log(countries.getNames("en", {select: "official"})); 
// { 'AF': 'Afghanistan', 'AL': 'Albania', ... }

Convert a full country name into its corresponding ISO codes using the following methods:

• getAlpha2Code(name, language)
• getAlpha3Code(name, language)

var countries = require("i18n-iso-countries");
console.log(countries.getAlpha2Code("United States of America", "en")); // US
console.log(countries.getAlpha3Code("United States of America", "en")); // USA

Use isValid(code) to check if a given string is a valid ISO 3166-1 country code (supports Alpha-2 and Alpha-3).

var countries = require("i18n-iso-countries");
console.log(countries.isValid("US")); // true
console.log(countries.isValid("USA")); // true
console.log(countries.isValid("XX")); // false

Use these methods to get complete mappings of country codes:

• getAlpha2Codes(): Returns an object mapping Alpha-2 codes to Alpha-3 codes.
• getAlpha3Codes(): Returns an object mapping Alpha-3 codes to Alpha-2 codes.
• getNumericCodes(): Returns an object mapping Numeric codes to Alpha-2 codes.

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

console.log(countries.getAlpha2Codes()); // { 'AF': 'AFG', 'AX': 'ALA', ... }
console.log(countries.getAlpha3Codes()); // { 'AFG': 'AF', 'ALA': 'AX', ... }
console.log(countries.getNumericCodes()); // { '004': 'AF', '008': 'AL', ... }

Use getName(code, lang, options) to retrieve a country name.

• code: ISO 3166-1 alpha-2, alpha-3, or numeric code (string or number).
• lang: The language code (e.g., 'en') for which the name should be retrieved.
• options: An object containing a select property to determine which type of name to return.

Supported options.select values:

• official: Returns the official name (default).
• all: Returns an array containing all available names.
• alias: Returns the alias name if available, otherwise the official name.

const countries = require('i18n-iso-countries');
countries.registerLocale(require('i18n-iso-countries/langs/en.json'));

// Get official name
const official = countries.getName('US', 'en', { select: 'official' });

// Get all names
const all = countries.getName('US', 'en', { select: 'all' });

Use getAlpha2Code(name, lang) to find the ISO 3166-1 alpha-2 code for a given country name in a specific language. The search is case-insensitive.

For a more robust search that ignores diacritics (e.g., treating 'é' as 'e'), use getSimpleAlpha2Code(name, lang).

const countries = require('i18n-iso-countries');
countries.registerLocale(require('i18n-iso-countries/langs/en.json'));

countries.getAlpha2Code('United States', 'en'); // 'US'
countries.getSimpleAlpha2Code('United States', 'en'); // 'US'

These functions allow you to normalize different ISO 3166-1 formats into a specific standard.

• toAlpha2(code): Converts alpha-3 or numeric codes to alpha-2. Accepts string or number.
• toAlpha3(code): Converts alpha-2 or numeric codes to alpha-3. Accepts string or number.

If the code is invalid or cannot be converted, the functions return undefined.

const countries = require('i18n-iso-countries');

countries.toAlpha2('USA'); // 'US'
countries.toAlpha2(840);  // 'US'

countries.toAlpha3('US'); // 'USA'
countries.toAlpha3(840);  // 'USA'