Usage Guides

🚀 Getting Started with ISO Codes

What are ISO Codes?

ISO codes are international standards that provide unique identifiers for countries, languages, currencies, and other entities. They ensure consistency across different systems and applications worldwide.

Why Use ISO Codes?

🌐 Universal recognition
📊 Data consistency
🔄 Easy integration
🎯 Reduced errors
📈 Better analytics

🌍 Using Country Codes (ISO 3166)

Code Formats

ISO 3166 provides three formats for country codes:

Alpha-2: 2-letter codes (US, GB, DE)
Alpha-3: 3-letter codes (USA, GBR, DEU)
Numeric: 3-digit codes (840, 826, 276)

Database Implementation

CREATE TABLE countries (
    alpha2 CHAR(2) PRIMARY KEY,
    alpha3 CHAR(3) UNIQUE NOT NULL,
    numeric CHAR(3) UNIQUE NOT NULL,
    name VARCHAR(100) NOT NULL,
    capital VARCHAR(100)
);

-- Example data
INSERT INTO countries VALUES 
('US', 'USA', '840', 'United States', 'Washington, D.C.'),
('GB', 'GBR', '826', 'United Kingdom', 'London'),
('DE', 'DEU', '276', 'Germany', 'Berlin');
                    

JavaScript Usage

// Convert country name to codes
function getCountryCodes(countryName) {
    const countries = {
        'United States': { alpha2: 'US', alpha3: 'USA', numeric: '840' },
        'United Kingdom': { alpha2: 'GB', alpha3: 'GBR', numeric: '826' },
        'Germany': { alpha2: 'DE', alpha3: 'DEU', numeric: '276' }
    };
    return countries[countryName] || null;
}

// Usage
const codes = getCountryCodes('United States');
console.log(codes); // { alpha2: 'US', alpha3: 'USA', numeric: '840' }
                    

💬 Implementing Language Codes (ISO 639)

Code Formats

ISO 639 provides multiple formats for language identification:

ISO 639-1: 2-letter codes (en, es, fr)
ISO 639-2: 3-letter codes (eng, spa, fra)
ISO 639-3: 3-letter codes (comprehensive)

HTML Language Attributes

<!-- Document language -->
<html lang="en">

<!-- Content in different languages -->
<p lang="es">Hola, mundo!</p>
<p lang="fr">Bonjour le monde!</p>
<p lang="de">Hallo Welt!</p>

<!-- Language with region -->
<html lang="en-US">  <!-- US English -->
<html lang="en-GB">  <!-- British English -->
                    

REST API Implementation

// Accept-Language header handling
app.get('/api/content', (req, res) => {
    const acceptedLanguages = req.headers['accept-language'];
    const preferredLang = parseLanguage(acceptedLanguages);
    
    // Return content in preferred language
    res.json({
        content: getLocalizedContent(preferredLang),
        language: preferredLang
    });
});

// URL-based language routing
app.get('/:lang(en|es|fr|de)/products', (req, res) => {
    const language = req.params.lang;
    res.render('products', { lang: language });
});
                    

💱 Working with Currency Codes (ISO 4217)

Code Structure

ISO 4217 currency codes are 3-letter alphabetic codes:

First 2 letters: Country code (ISO 3166)
Third letter: Currency identifier
Example: USD (US Dollar), EUR (Euro), GBP (British Pound)

E-commerce Implementation

class Price {
    constructor(amount, currency) {
        this.amount = amount;
        this.currency = currency; // ISO 4217 code
    }
    
    format(locale = 'en-US') {
        return new Intl.NumberFormat(locale, {
            style: 'currency',
            currency: this.currency
        }).format(this.amount);
    }
    
    convertTo(targetCurrency, exchangeRate) {
        return new Price(
            this.amount * exchangeRate,
            targetCurrency
        );
    }
}

// Usage
const price = new Price(99.99, 'USD');
console.log(price.format()); // $99.99
console.log(price.format('de-DE')); // 99,99 $
                    

Database Schema

CREATE TABLE currencies (
    code CHAR(3) PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    symbol VARCHAR(10),
    decimals INT DEFAULT 2
);

CREATE TABLE products (
    id INT PRIMARY KEY,
    name VARCHAR(100),
    price DECIMAL(10,2),
    currency CHAR(3),
    FOREIGN KEY (currency) REFERENCES currencies(code)
);
                    

📅 Date and Time Formats (ISO 8601)

Common Formats

ISO 8601 standardizes date and time representation:

JavaScript Date Handling

// Current date/time in ISO 8601
const now = new Date().toISOString();
console.log(now); // 2025-01-28T14:30:25.123Z

// Parsing ISO 8601 dates
const date = new Date('2025-01-28T14:30:25Z');

// Formatting for different locales
const options = {
    year: 'numeric',
    month: '2-digit',
    day: '2-digit',
    hour: '2-digit',
    minute: '2-digit',
    second: '2-digit',
    timeZoneName: 'short'
};

console.log(date.toLocaleDateString('en-US', options));
console.log(date.toLocaleDateString('de-DE', options));
                    

API Best Practices

// Always use ISO 8601 in APIs
{
    "createdAt": "2025-01-28T14:30:25.123Z",
    "updatedAt": "2025-01-28T15:45:10.456Z",
    "publishDate": "2025-01-28",
    "duration": "PT2H30M"  // 2 hours 30 minutes
}

// Database storage (always UTC)
CREATE TABLE events (
    id INT PRIMARY KEY,
    title VARCHAR(100),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    event_date DATE,
    start_time TIME,
    timezone VARCHAR(50)
);
                    

✅ Best Practices

🗄️ Database Design

Use ISO codes as primary keys when appropriate
Create lookup tables for validation
Index frequently queried codes
Store full names alongside codes

🌐 Internationalization

Support multiple language versions
Use proper locale-based formatting
Handle right-to-left scripts
Consider cultural differences

🔧 API Design

Accept multiple code formats
Provide clear error messages
Use consistent naming conventions
Version your APIs properly

📱 User Experience

Show user-friendly names
Provide search and autocomplete
Group related items logically
Handle deprecated codes gracefully

❌ Common Mistakes to Avoid

🚫 Don't Mix Code Formats

Be consistent with which ISO code format you use throughout your application.

// Bad: Mixing formats
countries = ['US', 'GBR', 'DE', 'FRA']

// Good: Consistent format
countries = ['US', 'GB', 'DE', 'FR']  // Alpha-2
countries = ['USA', 'GBR', 'DEU', 'FRA']  // Alpha-3
                        

🚫 Don't Hardcode Values

Always use the official ISO codes rather than creating your own.

// Bad: Custom codes
const languages = ['EN', 'SP', 'FR', 'GM'];

// Good: ISO 639-1 codes
const languages = ['en', 'es', 'fr', 'de'];
                        

🚫 Don't Assume Stability

ISO codes can change over time. Plan for updates and handle deprecated codes.

// Good: Handle deprecated codes
function normalizeCountryCode(code) {
    const deprecated = {
        'YU': 'RS', // Yugoslavia → Serbia
        'CS': 'CZ'  // Czechoslovakia → Czech Republic
    };
    return deprecated[code] || code;
}
                        

🚫 Don't Ignore Case Sensitivity

ISO codes have specific case conventions. Always normalize input.

// Good: Normalize case
function normalizeISOCode(code, type) {
    switch(type) {
        case 'country':
            return code.toUpperCase(); // US, GB, DE
        case 'language':
            return code.toLowerCase(); // en, es, fr
        case 'currency':
            return code.toUpperCase(); // USD, EUR, GBP
        default:
            return code;
    }
}
                        

📚 Guide Contents

🚀 Getting Started with ISO Codes

What are ISO Codes?

Why Use ISO Codes?

🌍 Using Country Codes (ISO 3166)

Code Formats

Database Implementation

JavaScript Usage

💬 Implementing Language Codes (ISO 639)

Code Formats

HTML Language Attributes

REST API Implementation

💱 Working with Currency Codes (ISO 4217)

Code Structure

E-commerce Implementation

Database Schema

📅 Date and Time Formats (ISO 8601)

Common Formats

JavaScript Date Handling

API Best Practices

✅ Best Practices

🗄️ Database Design

🌐 Internationalization

🔧 API Design

📱 User Experience

❌ Common Mistakes to Avoid

🚫 Don't Mix Code Formats

🚫 Don't Hardcode Values

🚫 Don't Assume Stability

🚫 Don't Ignore Case Sensitivity