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

name-to-code.mddocs/

Name to Code Conversion

Convert country names to country codes with support for both exact matching and diacritics-insensitive matching. Handles official names, aliases, and localized variations across 79 languages.

Capabilities

Get Alpha-2 Code from Name

Retrieves the Alpha-2 country code for a given country name in the specified language.

/**
 * Get Alpha-2 code from country name (exact matching)
 * @param name - Country name in the specified language
 * @param lang - ISO 639-1 language code
 * @returns Alpha-2 code or undefined if not found
 */
function getAlpha2Code(name: string, lang: string): string | undefined;

Usage Examples:

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

// English names
console.log(countries.getAlpha2Code("United States of America", "en")); // "US"
console.log(countries.getAlpha2Code("Germany", "en"));                   // "DE"
console.log(countries.getAlpha2Code("United Kingdom", "en"));            // "GB"
console.log(countries.getAlpha2Code("UK", "en"));                        // "GB" (alias)
console.log(countries.getAlpha2Code("Great Britain", "en"));             // "GB" (alias)

// Other languages
console.log(countries.getAlpha2Code("Deutschland", "de"));               // "DE"
console.log(countries.getAlpha2Code("Allemagne", "fr"));                 // "DE"
console.log(countries.getAlpha2Code("Alemania", "es"));                  // "DE"
console.log(countries.getAlpha2Code("ドイツ", "ja"));                      // "DE"

// Case sensitive exact matching
console.log(countries.getAlpha2Code("united states of america", "en")); // "US"
console.log(countries.getAlpha2Code("GERMANY", "en"));                   // "DE"

// Name not found
console.log(countries.getAlpha2Code("Nonexistent Country", "en"));       // undefined
console.log(countries.getAlpha2Code("Germany", "xx"));                   // undefined (unsupported language)

Get Simple Alpha-2 Code from Name

Retrieves the Alpha-2 country code with diacritics-insensitive matching for better internationalization support.

/**
 * Get Alpha-2 code from country name (diacritics-insensitive matching)
 * @param name - Country name in the specified language
 * @param lang - ISO 639-1 language code
 * @returns Alpha-2 code or undefined if not found
 */
function getSimpleAlpha2Code(name: string, lang: string): string | undefined;

Usage Examples:

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

// Standard matching (same as getAlpha2Code)
console.log(countries.getSimpleAlpha2Code("Germany", "en"));             // "DE"
console.log(countries.getSimpleAlpha2Code("France", "en"));              // "FR"

// Diacritics-insensitive matching
console.log(countries.getSimpleAlpha2Code("Cote d'Ivoire", "en"));       // "CI"
console.log(countries.getSimpleAlpha2Code("Côte d'Ivoire", "en"));       // "CI"
console.log(countries.getSimpleAlpha2Code("Bosnia and Herzegovina", "en")); // "BA"
console.log(countries.getSimpleAlpha2Code("Bosna i Hercegovina", "bs"));  // "BA"

// Works with accented characters
console.log(countries.getSimpleAlpha2Code("México", "es"));              // "MX"
console.log(countries.getSimpleAlpha2Code("Mexico", "es"));              // "MX"
console.log(countries.getSimpleAlpha2Code("Brasil", "pt"));              // "BR"
console.log(countries.getSimpleAlpha2Code("Brasil", "pt"));              // "BR"

// Case and diacritics insensitive
console.log(countries.getSimpleAlpha2Code("CÔTE D'IVOIRE", "fr"));       // "CI"
console.log(countries.getSimpleAlpha2Code("cote d ivoire", "fr"));       // "CI"

Get Alpha-3 Code from Name

Retrieves the Alpha-3 country code for a given country name in the specified language.

/**
 * Get Alpha-3 code from country name (exact matching)
 * @param name - Country name in the specified language
 * @param lang - ISO 639-1 language code
 * @returns Alpha-3 code or undefined if not found
 */
function getAlpha3Code(name: string, lang: string): string | undefined;

Usage Examples:

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

// English names
console.log(countries.getAlpha3Code("United States of America", "en")); // "USA"
console.log(countries.getAlpha3Code("Germany", "en"));                   // "DEU"
console.log(countries.getAlpha3Code("Japan", "en"));                     // "JPN"
console.log(countries.getAlpha3Code("United Kingdom", "en"));            // "GBR"

// Aliases work
console.log(countries.getAlpha3Code("UK", "en"));                        // "GBR"
console.log(countries.getAlpha3Code("Great Britain", "en"));             // "GBR"

// Other languages
console.log(countries.getAlpha3Code("日本", "ja"));                        // "JPN"
console.log(countries.getAlpha3Code("Japon", "fr"));                     // "JPN"
console.log(countries.getAlpha3Code("Japón", "es"));                     // "JPN"

// Name not found
console.log(countries.getAlpha3Code("Invalid Country", "en"));           // undefined

Get Simple Alpha-3 Code from Name

Retrieves the Alpha-3 country code with diacritics-insensitive matching.

/**
 * Get Alpha-3 code from country name (diacritics-insensitive matching)
 * @param name - Country name in the specified language
 * @param lang - ISO 639-1 language code
 * @returns Alpha-3 code or undefined if not found
 */
function getSimpleAlpha3Code(name: string, lang: string): string | undefined;

Usage Examples:

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

// Standard matching
console.log(countries.getSimpleAlpha3Code("Germany", "en"));             // "DEU"
console.log(countries.getSimpleAlpha3Code("France", "en"));              // "FRA"

// Diacritics-insensitive matching
console.log(countries.getSimpleAlpha3Code("Côte d'Ivoire", "fr"));       // "CIV"
console.log(countries.getSimpleAlpha3Code("Cote d'Ivoire", "fr"));       // "CIV"
console.log(countries.getSimpleAlpha3Code("México", "es"));              // "MEX"
console.log(countries.getSimpleAlpha3Code("Mexico", "es"));              // "MEX"

// Case and diacritics insensitive
console.log(countries.getSimpleAlpha3Code("BRASIL", "pt"));              // "BRA"
console.log(countries.getSimpleAlpha3Code("brasil", "pt"));              // "BRA"

Name Matching Behavior

Exact Matching (
getAlpha2Code
, 
getAlpha3Code
)

  • Case Insensitive: Converts both input and stored names to lowercase for comparison
  • Exact String Match: Requires precise character matching including diacritics and punctuation
  • Alias Support: Searches through both official names and aliases
  • Language Specific: Only searches within the specified language's country name data

Simple Matching (
getSimpleAlpha2Code
, 
getSimpleAlpha3Code
)

  • Diacritics Removal: Uses the 
    diacritics
    library to remove accents and special characters
  • Case Insensitive: Converts to lowercase after diacritics removal
  • Alias Support: Searches through both official names and aliases
  • More Flexible: Better for user input scenarios where exact spelling may vary

Search Algorithm

Both matching approaches:

  1. Normalize the input name (case conversion, optionally diacritics removal)
  2. Search through registered locale data for the specified language
  3. Check both string values and array values (for countries with multiple names/aliases)
  4. Return the Alpha-2 code for the first match found
  5. Return 
    undefined
    if no match is found

Error Handling

All name-to-code conversion functions handle errors gracefully:

  • Invalid Language: Returns 
    undefined
    for unsupported language codes
  • Name Not Found: Returns 
    undefined
    when no matching country name is found
  • Empty Input: Returns 
    undefined
    for empty or null name inputs
  • No Exceptions: Functions never throw exceptions, always return 
    undefined
    for invalid inputs

Language Support

Name-to-code conversion works with all 79 supported languages. Some examples:

// European languages
console.log(countries.getAlpha2Code("Deutschland", "de"));    // "DE" (German)
console.log(countries.getAlpha2Code("Francia", "es"));        // "FR" (Spanish)
console.log(countries.getAlpha2Code("Италия", "ru"));         // "IT" (Russian)

// Asian languages
console.log(countries.getAlpha2Code("中国", "zh"));            // "CN" (Chinese)
console.log(countries.getAlpha2Code("인도", "ko"));            // "IN" (Korean)
console.log(countries.getAlpha2Code("อินเดีย", "th"));        // "IN" (Thai)

// African languages
console.log(countries.getAlpha2Code("Misri", "sw"));          // "EG" (Swahili)
console.log(countries.getAlpha2Code("Nijeriya", "ha"));       // "NG" (Hausa)

Browser Environment Notes

In browser environments, ensure the required language data is registered before attempting name-to-code conversion:

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

// Register required languages
countries.registerLocale(require("i18n-iso-countries/langs/en.json"));
countries.registerLocale(require("i18n-iso-countries/langs/de.json"));

// Now conversion works
console.log(countries.getAlpha2Code("Germany", "en"));        // "DE"
console.log(countries.getAlpha2Code("Deutschland", "de"));    // "DE"

// Unregistered language returns undefined
console.log(countries.getAlpha2Code("Francia", "es"));        // undefined

Performance Considerations

  • Exact Matching: Faster performance due to simpler string comparison
  • Simple Matching: Slightly slower due to diacritics processing but more user-friendly
  • Linear Search: Both approaches use linear search through country names (not indexed)
  • Memory Usage: Functions share the same underlying locale data, no additional memory overhead
  • Recommendation: Use exact matching for known/controlled inputs, simple matching for user inputs