Accept-Language Header — Using the Accept-Language HTTP Header for i18n

// i18n/accept-language.js — Parse Accept-Language header
class AcceptLanguageParser {
    // Parse the Accept-Language header value
    static parse(header) {
        if (!header) return [];

        return header
            .split(',')
            .map(entry => {
                const [locale, qValue] = entry.trim().split(';q=');
                return {
                    locale: locale.trim(),
                    quality: qValue ? parseFloat(qValue) : 1.0
                };
            })
            .filter(entry => entry.quality > 0)
            .sort((a, b) => b.quality - a.quality);
    }

    // Find best match among supported locales
    static negotiate(header, supportedLocales) {
        const preferences = this.parse(header);

        for (const pref of preferences) {
            const match = this.findMatch(pref.locale, supportedLocales);
            if (match) return match;
        }

        return supportedLocales[0] || 'en-US';
    }

    // Match a locale against supported list with fallbacks
    static findMatch(locale, supported) {
        // Normalize: replace underscores with hyphens
        const normalized = locale.replace(/_/g, '-');

        // Exact match
        if (supported.includes(normalized)) return normalized;

        // Language + region (with different separator)
        const variants = [
            normalized,
            normalized.toLowerCase(),
            normalized.toUpperCase()
        ];

        for (const variant of variants) {
            if (supported.includes(variant)) return variant;
        }

        // Language-only match
        const lang = normalized.split('-')[0].toLowerCase();
        const langMatch = supported.find(s => {
            const supportedLang = s.toLowerCase().split('-')[0];
            return supportedLang === lang;
        });

        if (langMatch) return langMatch;

        // Try parent locale (e.g., es-MX -> es-419 -> es)
        if (normalized.includes('-')) {
            const parent = normalized.split('-')[0];
            return supported.find(s => {
                const supportedLang = s.toLowerCase().split('-')[0];
                return supportedLang === parent;
            }) || null;
        }

        return null;
    }

    // Get all matched locales with quality scores
    static matchAll(header, supported) {
        const preferences = this.parse(header);
        const results = [];

        for (const pref of preferences) {
            const match = this.findMatch(pref.locale, supported);
            if (match) {
                results.push({
                    requested: pref.locale,
                    matched: match,
                    quality: pref.quality
                });
            }
        }

        return results;
    }
}

// Usage
const header = 'fr-CH, fr;q=0.9, en;q=0.8, de;q=0.5';
const supported = ['en-US', 'fr-FR', 'de-DE', 'fr-CH'];

console.log('Parsed:', AcceptLanguageParser.parse(header));
console.log('Negotiated:', AcceptLanguageParser.negotiate(header, supported));
console.log('All matches:', AcceptLanguageParser.matchAll(header, supported));

// middleware/i18n-negotiation.js — Express middleware for locale negotiation
class I18nNegotiationMiddleware {
    constructor(options = {}) {
        this.options = {
            supportedLocales: options.supportedLocales || ['en-US'],
            defaultLocale: options.defaultLocale || 'en-US',
            cookieName: options.cookieName || 'locale',
            ...options
        };
    }

    middleware() {
        return (req, res, next) => {
            // 1. Check cookie (explicit user choice always wins)
            const cookieLocale = req.cookies?.[this.options.cookieName];
            if (cookieLocale && this.options.supportedLocales.includes(cookieLocale)) {
                req.locale = cookieLocale;
                this.setResponseHeaders(res, cookieLocale);
                return next();
            }

            // 2. Negotiate from Accept-Language
            const acceptLanguage = req.headers['accept-language'];
            const negotiated = AcceptLanguageParser.negotiate(
                acceptLanguage,
                this.options.supportedLocales
            );

            req.locale = negotiated;
            this.setResponseHeaders(res, negotiated);
            next();
        };
    }

    setResponseHeaders(res, locale) {
        res.setHeader('Content-Language', locale);

        // Vary header tells caches that content varies by language
        res.setHeader('Vary', 'Accept-Language');
    }

    // Helper to generate locale-specific URLs
    static localeUrl(req, targetLocale) {
        const url = new URL(req.url, `${req.protocol}://${req.headers.host}`);
        url.searchParams.set('lang', targetLocale);
        return url.toString();
    }
}

// Set Content-Language in responses
// This tells browsers and search engines what language the content is in

// Example: Express route
app.get('/products', (req, res) => {
    const locale = req.locale; // Set by middleware
    const products = getProducts(locale);

    res.setHeader('Content-Language', locale);
    res.setHeader('Vary', 'Accept-Language, Cookie');

    res.render('products', {
        locale,
        products,
        // hreflang alternatives
        alternates: [
            { locale: 'en-US', url: '/en/products' },
            { locale: 'es-ES', url: '/es/products' },
            { locale: 'fr-FR', url: '/fr/products' }
        ]
    });
});

// The Vary: Accept-Language header is critical for CDN caching
// Without it, a CDN might serve English content to French users

// Advanced: Quality-weighted locale negotiation
class QualityNegotiator {
    constructor(strategy = 'highest') {
        this.strategy = strategy; // 'highest', 'average', 'threshold'
    }

    negotiate(header, supportedLocales, options = {}) {
        const preferences = AcceptLanguageParser.parse(header);

        // Score each supported locale
        const scored = supportedLocales.map(locale => {
            let score = 0;
            let matches = [];

            preferences.forEach(pref => {
                const match = this.matchScore(pref.locale, locale);
                if (match > 0) {
                    score += match * pref.quality;
                    matches.push({ locale: pref.locale, score: match });
                }
            });

            return { locale, score, matches };
        });

        // Sort by score descending
        scored.sort((a, b) => b.score - a.score);

        // Apply minimum threshold
        if (options.minScore && scored[0]?.score < options.minScore) {
            return options.fallback || supportedLocales[0];
        }

        return scored[0]?.locale || supportedLocales[0];
    }

    matchScore(requested, supported) {
        const req = requested.replace(/_/g, '-').toLowerCase();
        const sup = supported.toLowerCase();

        // Exact match = highest score
        if (req === sup) return 1.0;

        // Same language + region (case difference)
        if (req === sup) return 0.95;

        // Same language
        const reqLang = req.split('-')[0];
        const supLang = sup.split('-')[0];
        if (reqLang === supLang) return 0.7;

        // Related language family
        const families = {
            'en': ['en', 'de'],  // Germanic
            'de': ['en', 'de'],
            'es': ['es', 'fr', 'it', 'pt'],  // Romance
            'fr': ['es', 'fr', 'it', 'pt'],
            'it': ['es', 'fr', 'it', 'pt'],
            'pt': ['es', 'fr', 'it', 'pt'],
        };

        if (families[reqLang]?.includes(supLang)) return 0.3;

        return 0;
    }
}

const negotiator = new QualityNegotiator();
const header = 'en-GB;q=0.9, fr-FR;q=0.8';
const supported = ['en-US', 'en-GB', 'fr-FR', 'de-DE'];
console.log('Quality negotiated:', negotiator.negotiate(header, supported));