Language Tags — BCP 47 Language Tags and Locale Codes Explained

// i18n/language-tags.js — BCP 47 tag parsing
class LanguageTag {
    constructor(tag) {
        this.tag = tag;
        this.language = null;
        this.script = null;
        this.region = null;
        this.variant = null;
        this.extensions = [];

        this.parse(tag);
    }

    parse(tag) {
        const parts = tag.split('-');

        // First part: primary language (ISO 639-1 or 639-3)
        if (parts.length > 0) {
            this.language = parts[0].toLowerCase();
        }

        // Second part: could be script (ISO 15924) or region (ISO 3166-1)
        if (parts.length > 1) {
            // Script codes are 4 characters, title case (e.g., "Latn")
            if (parts[1].length === 4) {
                this.script = parts[1].charAt(0).toUpperCase() + parts[1].slice(1).toLowerCase();
            }
            // Region codes are 2 letters (ISO 3166-1) or 3 digits (UN M.49)
            else if (parts[1].length === 2 || /^\d{3}$/.test(parts[1])) {
                this.region = parts[1].toUpperCase();
            }
        }

        // Third part: region (if second was script)
        if (parts.length > 2) {
            const third = parts[2];
            if (third.length === 2 || /^\d{3}$/.test(third)) {
                this.region = third.toUpperCase();
            }
        }

        // Remaining parts: variants or extensions
        for (let i = 3; i < parts.length; i++) {
            if (parts[i].length >= 5 && /^[a-z]/.test(parts[i])) {
                this.variant = parts[i];
            } else if (parts[i].length === 1) {
                this.extensions.push(parts[i]);
            }
        }
    }

    toString() {
        let result = this.language;
        if (this.script) result += `-${this.script}`;
        if (this.region) result += `-${this.region}`;
        if (this.variant) result += `-${this.variant}`;
        return result;
    }

    // Check if this tag matches another, considering fallbacks
    matches(other, options = {}) {
        const otherTag = typeof other === 'string' ? new LanguageTag(other) : other;

        // Exact match
        if (this.tag === otherTag.tag) return true;

        // Language + region match (e.g., en-US matches en-US)
        if (this.language === otherTag.language &&
            this.region && otherTag.region &&
            this.region === otherTag.region) return true;

        // Language match with fallback (e.g., en-US matches en)
        if (options.fallback && this.language === otherTag.language) return true;

        return false;
    }

    // Get the parent tag (for fallback chains)
    parent() {
        if (this.region) {
            return new LanguageTag(this.language + (this.script ? `-${this.script}` : ''));
        }
        if (this.script) {
            return new LanguageTag(this.language);
        }
        return null;
    }

    // Validate the tag structure
    static validate(tag) {
        const pattern = /^([a-z]{2,3})(-[A-Z][a-z]{3})?(-[A-Z]{2}|\-\d{3})?(-[a-z]{5,})?(-[a-z])?$/i;
        return pattern.test(tag);
    }
}

// Usage examples
const tags = [
    new LanguageTag('en-US'),
    new LanguageTag('zh-Hans-CN'),
    new LanguageTag('sr-Latn-RS'),
    new LanguageTag('es-419'),
    new LanguageTag('en'),
];

tags.forEach(t => {
    console.log(`${t.tag}: lang=${t.language}, script=${t.script || 'none'}, region=${t.region || 'none'}`);
});

// Fallback chain example
const userTag = new LanguageTag('es-MX');
console.log('Fallback chain:');
let current = userTag;
while (current) {
    console.log(`  ${current.tag}`);
    current = current.parent();
}

// i18n/locale-resolver.js — Find best locale match
class LocaleResolver {
    constructor(supportedLocales = []) {
        this.locales = supportedLocales.map(l => new LanguageTag(l));
    }

    // Find best match for user locale
    resolve(userLocale) {
        const userTag = new LanguageTag(userLocale);

        // 1. Exact match
        const exact = this.locales.find(l => l.tag === userTag.tag);
        if (exact) return exact.tag;

        // 2. Language + region match
        const regionMatch = this.locales.find(l =>
            l.language === userTag.language &&
            l.region === userTag.region
        );
        if (regionMatch) return regionMatch.tag;

        // 3. Language match (any region)
        const langMatch = this.locales.find(l =>
            l.language === userTag.language
        );
        if (langMatch) return langMatch.tag;

        // 4. Script match (for Chinese, Arabic, etc.)
        if (userTag.script) {
            const scriptMatch = this.locales.find(l =>
                l.script === userTag.script
            );
            if (scriptMatch) return scriptMatch.tag;
        }

        // 5. Default to first supported
        return this.locales[0]?.tag || 'en-US';
    }

    // Build Accept-Language style ranking
    prioritize(locales) {
        return locales
            .map(locale => ({ tag: locale, tagObj: new LanguageTag(locale) }))
            .map(item => ({
                ...item,
                priority: this.calculatePriority(item.tagObj)
            }))
            .sort((a, b) => b.priority - a.priority)
            .map(item => item.tag);
    }

    calculatePriority(tag) {
        let score = 0;
        if (this.locales.find(l => l.tag === tag.tag)) score += 100;
        if (this.locales.find(l => l.language === tag.language)) score += 50;
        if (this.locales.find(l => l.script === tag.script)) score += 25;
        return score;
    }
}

const resolver = new LocaleResolver(['en-US', 'en-GB', 'es-ES', 'fr-FR', 'zh-Hans-CN']);

console.log('User es-MX resolves to:', resolver.resolve('es-MX'));
console.log('User en resolves to:', resolver.resolve('en'));
console.log('User zh-Hant-TW resolves to:', resolver.resolve('zh-Hant-TW'));