i18n Routing — URL-Based Locale Routing Strategies

// server/i18n-router.js — Path prefix routing with Express
const express = require('express');
const path = require('path');

class I18nRouter {
    constructor(options = {}) {
        this.options = {
            supportedLocales: options.supportedLocales || ['en', 'es', 'fr', 'ar'],
            defaultLocale: options.defaultLocale || 'en',
            translationsDir: options.translationsDir || path.join(__dirname, '..', 'locales'),
            ...options
        };
    }

    // Middleware to detect locale from URL path
    localeMiddleware() {
        return (req, res, next) => {
            // Extract locale from path: /en/products → en
            const match = req.path.match(/^\/(\w{2}(?:-\w{2})?)(\/|$)/);
            const detectedLocale = match ? match[1] : null;

            if (this.options.supportedLocales.includes(detectedLocale)) {
                req.locale = detectedLocale;
                // Strip locale from path for route matching
                req.url = req.path.replace(/^\/\w{2}(?:-\w{2})?/, '') || '/';
            } else {
                // Not a valid locale in path — redirect to default
                if (detectedLocale) {
                    // Unknown locale prefix — redirect to default
                    return this.redirectToLocale(req, res, this.options.defaultLocale);
                }
                req.locale = this.options.defaultLocale;
            }

            // Store original URL for hreflang links
            req.originalPath = req.originalUrl;

            res.locals.locale = req.locale;
            res.locals.alternates = this.getAlternates(req);

            next();
        };
    }

    // Generate hreflang alternate URLs
    getAlternates(req) {
        const baseUrl = `${req.protocol}://${req.headers.host}`;
        const pathWithoutLocale = req.path.replace(/^\/(\w{2}(?:-\w{2})?)/, '');

        return this.options.supportedLocales.map(locale => ({
            locale,
            href: `${baseUrl}/${locale}${pathWithoutLocale || '/'}`
        }));
    }

    // Redirect to locale-prefixed URL
    redirectToLocale(req, res, locale) {
        const path = req.path || '/';
        // If the path already starts with a locale, replace it
        const newPath = path.replace(/^\/(\w{2}(?:-\w{2})?)/, `/${locale}`);
        res.redirect(302, `/${locale}${newPath}`);
    }

    // Detect locale from Accept-Language for first visit
    detectFromBrowser(req) {
        const acceptLanguage = req.headers['accept-language'];
        if (!acceptLanguage) return this.options.defaultLocale;

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

        for (const pref of preferences) {
            if (this.options.supportedLocales.includes(pref.locale)) {
                return pref.locale;
            }
        }

        return this.options.defaultLocale;
    }

    // Setup routes
    setup(app) {
        // Root path — redirect to detected locale
        app.get('/', (req, res) => {
            const locale = req.cookies?.locale
                || this.detectFromBrowser(req)
                || this.options.defaultLocale;
            res.redirect(302, `/${locale}/`);
        });

        // Apply locale middleware
        app.use(this.localeMiddleware());

        // Serve localized static files
        app.use((req, res, next) => {
            const locale = req.locale;
            // Example: serve different translation files
            req.t = (key) => {
                // Translation lookup logic
                return key;
            };
            next();
        });
    }
}

module.exports = I18nRouter;

// next.config.js — Next.js built-in i18n routing
module.exports = {
    i18n: {
        // Supported locales
        locales: ['en', 'es', 'fr', 'de', 'ar', 'ja'],

        // Default locale (used as fallback and for root path)
        defaultLocale: 'en',

        // Locale detection from Accept-Language
        localeDetection: true,

        // Domain-based routing (optional)
        domains: [
            {
                domain: 'example.com',
                defaultLocale: 'en',
            },
            {
                domain: 'example.es',
                defaultLocale: 'es',
            },
            {
                domain: 'example.fr',
                defaultLocale: 'fr',
            },
            {
                domain: 'example.de',
                defaultLocale: 'de',
            },
        ],
    },
};

// pages/[locale]/products/[id].js — Locale-aware Next.js page
import { useRouter } from 'next/router';
import { serverSideTranslations } from 'next-i18next/serverSideTranslations';

export default function ProductPage({ product }) {
    const router = useRouter();
    const { locale } = router;

    return (
        <div>
            <h1>{product.name}</h1>
            <p>{product.description}</p>

            {/* Locale switcher links */}
            <nav aria-label="Language switcher">
                {router.locales.map(localeCode => (
                    <a
                        key={localeCode}
                        href={router.asPath}
                        locale={localeCode}
                        hrefLang={localeCode}
                    >
                        {localeCode.toUpperCase()}
                    </a>
                ))}
            </nav>
        </div>
    );
}

export async function getServerSideProps({ locale, params }) {
    return {
        props: {
            ...(await serverSideTranslations(locale, ['common', 'product'])),
            product: await getProduct(params.id, locale),
        },
    };
}

// server/locale-redirect.js — Smart locale redirects
class LocaleRedirector {
    constructor(options = {}) {
        this.supportedLocales = options.supportedLocales || ['en', 'es', 'fr'];
        this.defaultLocale = options.defaultLocale || 'en';
    }

    // Determine the best locale for a first-time visitor
    determineLocale(req) {
        // Priority: 1. Cookie, 2. Accept-Language, 3. Default
        const cookie = req.cookies?.locale;
        if (cookie && this.supportedLocales.includes(cookie)) {
            return cookie;
        }

        const acceptLanguage = req.headers['accept-language'];
        if (acceptLanguage) {
            const match = acceptLanguage
                .split(',')
                .map(e => {
                    const [locale, q] = e.trim().split(';q=');
                    return { locale: locale.split('-')[0], quality: q ? parseFloat(q) : 1.0 };
                })
                .sort((a, b) => b.quality - a.quality)
                .find(pref => this.supportedLocales.includes(pref.locale));

            if (match) return match.locale;
        }

        return this.defaultLocale;
    }

    // Handle root path redirect
    handleRoot(req, res) {
        const locale = this.determineLocale(req);
        const cookieLocale = req.cookies?.locale;

        // If user has a saved preference, use it
        if (cookieLocale && this.supportedLocales.includes(cookieLocale)) {
            return res.redirect(302, `/${cookieLocale}/`);
        }

        // Otherwise redirect based on browser detection
        return res.redirect(302, `/${locale}/`);
    }

    // Handle 404 for locale paths
    handleNotFound(req, res) {
        const locale = req.locale || this.defaultLocale;
        res.status(404).render('404', { locale });
    }

    // Handle locale mismatch — redirect to correct locale
    handleMismatch(req, res, targetLocale) {
        const path = req.path.replace(/^\/(\w{2}(?:-\w{2})?)/, `/${targetLocale}`);
        res.redirect(301, path);
    }
}