or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

code-conversion.mdindex.mdlistings-validation.mdlocale-management.mdname-retrieval.mdname-to-code.md
tile.json

index.mddocs/

i18n ISO Countries

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.

Package Information

  • Package Name: i18n-iso-countries
  • Package Type: npm
  • Language: JavaScript with TypeScript definitions
  • Installation: 
    npm install i18n-iso-countries

Core Imports

// Node.js (all locales pre-loaded)
const countries = require("i18n-iso-countries");
// TypeScript with Node.js
import * as countries from "i18n-iso-countries";
// Browser (requires manual locale registration)
const countries = require("i18n-iso-countries");
countries.registerLocale(require("i18n-iso-countries/langs/en.json"));
countries.registerLocale(require("i18n-iso-countries/langs/fr.json"));
// TypeScript with specific imports
import { getName, getAlpha2Code, registerLocale, Alpha2Code } from "i18n-iso-countries";

Basic Usage

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

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

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

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

// Validate codes
console.log(countries.isValid("US")); // true
console.log(countries.isValid("XX")); // false

Architecture

i18n ISO Countries consists of several key components:

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

Capabilities

Country Name Retrieval

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

function getName(
  code: string | number | Alpha2Code | Alpha3Code,
  lang: string,
  options?: { select: 'official' | 'alias' | 'all' }
): string | string[] | undefined;

function getNames(
  lang: string,
  options?: { select: 'official' | 'alias' | 'all' }
): LocalizedCountryNames<GetNameOptions>;

Name Retrieval

Code Conversion

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

function alpha2ToAlpha3(alpha2: string): string | undefined;
function alpha3ToAlpha2(alpha3: string): string | undefined;
function toAlpha2(code: string | number | Alpha2Code | Alpha3Code): string | undefined;
function toAlpha3(code: string | number | Alpha2Code | Alpha3Code): string | undefined;

Code Conversion

Name to Code Conversion

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

function getAlpha2Code(name: string, lang: string): string | undefined;
function getAlpha3Code(name: string, lang: string): string | undefined;
function getSimpleAlpha2Code(name: string, lang: string): string | undefined;
function getSimpleAlpha3Code(name: string, lang: string): string | undefined;

Name to Code Conversion

Code Listings and Validation

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

function getAlpha2Codes(): { [alpha2Key: string]: string };
function getAlpha3Codes(): { [alpha3Key: string]: string };
function getNumericCodes(): { [numericKey: string]: string };
function isValid(code: string | number): boolean;

Code Listings and Validation

Locale Management

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

function registerLocale(localeData: {
  locale: string;
  countries: { [alpha2Key: string]: string | string[] };
}): void;

function getSupportedLanguages(): string[];
function langs(): string[];

Locale Management

Types

interface GetNameOptions {
  select: 'all' | 'official' | 'alias';
}

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

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

type LocaleData = {
  locale: string;
  countries: { [alpha2Key: string]: string[] | string };
};

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

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