Skip to content

Speakr is a personal, self-hosted web application designed for transcribing audio recordings

Python
15.0 KB
Raw Blame
/**
 * Lightweight i18n (internationalization) system for Speakr
 * Handles loading and managing translations with template variable support
 */

class I18n {
    constructor() {
        this.translations = {};
        this.currentLocale = 'en';
        this.fallbackLocale = 'en';
        this.loadedLocales = new Set();
        // Resolved once init() has loaded the translations, so code that
        // renders before then (the shared page header) can wait for them.
        this.isReady = false;
        this.ready = new Promise(resolve => { this._resolveReady = resolve; });
    }

    /**
     * Initialize i18n with default locale
     * @param {string} locale - Initial locale code (e.g., 'en', 'es', 'fr', 'zh')
     */
    async init(locale = 'en') {
        // Get saved locale from localStorage or use browser language
        const savedLocale = localStorage.getItem('preferredLanguage');
        const browserLocale = navigator.language.split('-')[0];
        
        this.currentLocale = savedLocale || locale || browserLocale || 'en';
        
        // Load the initial locale
        await this.loadLocale(this.currentLocale);
        
        // Load fallback locale if different
        if (this.currentLocale !== this.fallbackLocale) {
            await this.loadLocale(this.fallbackLocale);
        }

        this._markReady();
    }

    _markReady() {
        if (this.isReady) return;
        this.isReady = true;
        this._resolveReady();
        window.dispatchEvent(new CustomEvent('i18nReady', { detail: { locale: this.currentLocale } }));
    }

    /**
     * Use translations embedded in the page (window.__I18N_BOOTSTRAP, from
     * templates/includes/i18n_bootstrap.html), so the first render is already
     * translated and no locale file is fetched for it. The locale is chosen as
     * in init(). When the chosen locale is not among the embedded ones, ready
     * stays pending and the locale is fetched by init() as before.
     * @param {{locale: string, translations: Object<string, Object>}} data
     * @returns {boolean} true when the translations are ready
     */
    applyBootstrap(data) {
        if (!data || typeof data !== 'object' || !data.translations || typeof data.translations !== 'object') {
            return false;
        }
        for (const [code, table] of Object.entries(data.translations)) {
            if (table && typeof table === 'object') {
                this.translations[code] = table;
                this.loadedLocales.add(code);
            }
        }
        let savedLocale = null;
        try {
            savedLocale = localStorage.getItem('preferredLanguage');
        } catch (e) {
            savedLocale = null;
        }
        this.currentLocale = savedLocale || data.locale || this.fallbackLocale;
        if (!this.loadedLocales.has(this.currentLocale) || !this.loadedLocales.has(this.fallbackLocale)) {
            return false;
        }
        this._markReady();
        return true;
    }

    /**
     * Load translations for a specific locale
     * @param {string} locale - Locale code to load
     */
    async loadLocale(locale) {
        if (this.loadedLocales.has(locale)) {
            return; // Already loaded
        }

        try {
            // 'no-cache' forces a conditional revalidation so a browser (or
            // proxy) heuristic cache can never serve a previous release's
            // locale file against newer templates — the "Translation not
            // found" spam after upgrades (issue #357).
            const response = await fetch(`/static/locales/${locale}.json`, { cache: 'no-cache' });
            if (!response.ok) {
                throw new Error(`Failed to load locale: ${locale}`);
            }
            
            const translations = await response.json();
            this.translations[locale] = translations;
            this.loadedLocales.add(locale);
            
            console.log(`Loaded locale: ${locale}`);
        } catch (error) {
            console.error(`Error loading locale ${locale}:`, error);
            
            // If failed to load requested locale and it's not the fallback, try fallback
            if (locale !== this.fallbackLocale) {
                console.log(`Failed to load ${locale}, will use ${this.fallbackLocale} as fallback`);
                // Don't change currentLocale - keep user's preference
                // Just ensure fallback translations are available
                await this.loadLocale(this.fallbackLocale);
            }
        }
    }

    /**
     * Change the current locale
     * @param {string} locale - New locale code
     */
    async setLocale(locale) {
        await this.loadLocale(locale);
        this.currentLocale = locale;
        localStorage.setItem('preferredLanguage', locale);
        
        // Dispatch custom event for locale change
        window.dispatchEvent(new CustomEvent('localeChanged', { detail: { locale } }));
    }

    /**
     * Get the current locale
     * @returns {string} Current locale code
     */
    getLocale() {
        return this.currentLocale;
    }

    /**
     * The interface locale as a language tag for Intl and the toLocale*String
     * methods, so dates and numbers follow the selected language (#480).
     * Undefined, which Intl reads as the browser default, when the stored code
     * is not a valid tag: Intl throws on one, and a date should still render.
     * @returns {string|undefined}
     */
    getIntlLocale() {
        try {
            return Intl.getCanonicalLocales(this.currentLocale)[0];
        } catch (e) {
            return undefined;
        }
    }

    /**
     * Get available locales
     * @returns {Array} List of available locale codes
     */
    getAvailableLocales() {
        return [
            { code: 'en', name: 'English', nativeName: 'English' },
            { code: 'es', name: 'Spanish', nativeName: 'Español' },
            { code: 'fr', name: 'French', nativeName: 'Français' },
            { code: 'zh', name: 'Chinese', nativeName: '中文' },
            { code: 'ru', name: 'Russian', nativeName: 'Русский' },
            { code: 'pt-BR', name: 'Portuguese (Brazil)', nativeName: 'Português (Brasil)' },
        ];
    }

    /**
     * Translate a key with optional parameters
     * @param {string} key - Translation key (e.g., 'common.save' or 'nav.upload')
     * @param {Object} params - Optional parameters for template replacement
     * @param {string} locale - Optional specific locale (defaults to current)
     * @returns {string} Translated text
     */
    t(key, params = {}, locale = null) {
        const targetLocale = locale || this.currentLocale;
        
        // Get translation from current locale or fallback
        let translation = this.getNestedTranslation(targetLocale, key);
        
        if (!translation && targetLocale !== this.fallbackLocale) {
            translation = this.getNestedTranslation(this.fallbackLocale, key);
        }
        
        if (!translation) {
            // Warn ONCE per missing key. Without this, a missing key used in a
            // component that re-renders rapidly (e.g. the chat modal during a
            // drag) floods the console with the same warning every frame.
            if (!this._warnedMissingKeys) this._warnedMissingKeys = new Set();
            if (!this._warnedMissingKeys.has(key)) {
                this._warnedMissingKeys.add(key);
                console.warn(`Translation not found for key: ${key}`);
            }
            return key; // Return the key itself as fallback
        }
        
        // Replace template variables
        return this.interpolate(translation, params);
    }

    /**
     * Get nested translation value from object
     * @param {string} locale - Locale to search in
     * @param {string} key - Dot-separated key path
     * @returns {string|null} Translation value or null
     */
    getNestedTranslation(locale, key) {
        if (!this.translations[locale]) {
            return null;
        }
        
        const keys = key.split('.');
        let value = this.translations[locale];
        
        for (const k of keys) {
            if (value && typeof value === 'object' && k in value) {
                value = value[k];
            } else {
                return null;
            }
        }
        
        return typeof value === 'string' ? value : null;
    }

    /**
     * Replace template variables in translation string
     * @param {string} text - Text with placeholders like {{variable}}
     * @param {Object} params - Parameters to replace
     * @returns {string} Interpolated text
     */
    interpolate(text, params) {
        return text.replace(/\{\{(\w+)\}\}/g, (match, key) => {
            return params.hasOwnProperty(key) ? params[key] : match;
        });
    }

    /**
     * Handle pluralization
     * @param {string} key - Base translation key
     * @param {number} count - Count for pluralization
     * @param {Object} params - Additional parameters
     * @returns {string} Translated text with proper pluralization
     */
    tc(key, count, params = {}) {
        const pluralKey = count === 1 ? key : `${key}Plural`;
        return this.t(pluralKey, { ...params, count });
    }

    /**
     * Format date according to locale
     * @param {Date|string} date - Date to format
     * @param {Object} options - Intl.DateTimeFormat options
     * @returns {string} Formatted date string
     */
    formatDate(date, options = {}) {
        const d = date instanceof Date ? date : new Date(date);
        return new Intl.DateTimeFormat(this.getIntlLocale(), options).format(d);
    }

    /**
     * Format number according to locale
     * @param {number} number - Number to format
     * @param {Object} options - Intl.NumberFormat options
     * @returns {string} Formatted number string
     */
    formatNumber(number, options = {}) {
        return new Intl.NumberFormat(this.getIntlLocale(), options).format(number);
    }

    /**
     * Format a percentage in the interface language: "12.5%", "12,5 %" in
     * German (#480). The value is on the 0-100 scale, as every caller holds
     * it: formatPercent(12.5) is 12.5 %, not 1250 %.
     * @param {number} percent - Percentage, 0-100 (more is allowed)
     * @param {object} options - Intl.NumberFormat options; at most one decimal by default
     * @returns {string} Formatted percentage
     */
    formatPercent(percent, options = {}) {
        const value = Number(percent);
        return this.formatNumber(Number.isFinite(value) ? value / 100 : 0,
            { maximumFractionDigits: 1, ...options, style: 'percent' });
    }

    /**
     * Format file size with appropriate unit, at most one decimal, in the
     * interface language's number format: "1.5 MB", "1,5 MB" in German (#481).
     * src/utils/localization.py format_file_size() is the server-side twin.
     * @param {number} bytes - Size in bytes
     * @returns {string} Formatted file size
     */
    formatFileSize(bytes) {
        const units = ['bytes', 'kilobytes', 'megabytes', 'gigabytes', 'terabytes'];
        const size = Math.max(Number(bytes) || 0, 0);
        let unit = 0;
        while (unit < units.length - 1 && size >= 1024 ** (unit + 1)) unit++;
        // 1023.97 KB would round to "1024 KB"; that is 1 MB.
        if (unit < units.length - 1 && Math.round(size / 1024 ** unit * 10) / 10 >= 1024) unit++;
        // No grouping: below 1 PB the count is under 1024, and German "1.023 B" reads as 1.023.
        const count = this.formatNumber(size / 1024 ** unit, { maximumFractionDigits: 1, useGrouping: false });
        return this.t(`fileSize.${units[unit]}`, { count });
    }

    /**
     * Format duration with appropriate unit
     * @param {number} seconds - Duration in seconds
     * @returns {string} Formatted duration
     */
    formatDuration(seconds) {
        if (seconds < 60) {
            return this.tc('duration.seconds', Math.round(seconds), { count: Math.round(seconds) });
        } else if (seconds < 3600) {
            const minutes = Math.round(seconds / 60);
            return this.tc('duration.minutes', minutes, { count: minutes });
        } else {
            const hours = Math.round(seconds / 3600 * 10) / 10;
            return this.tc('duration.hours', hours, { count: hours });
        }
    }

    /**
     * Format relative time (e.g., "2 hours ago")
     * @param {Date|string} date - Date to format
     * @returns {string} Formatted relative time
     */
    formatRelativeTime(date) {
        // Backend timestamps are naive UTC; append 'Z' for string inputs so the
        // elapsed-time diff is computed against true UTC, not a local mis-parse.
        let d;
        if (date instanceof Date) {
            d = date;
        } else {
            let s = date;
            if (typeof s === 'string' && /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/.test(s) && !/(?:Z|[+-]\d{2}:?\d{2})$/.test(s)) {
                s = s.replace(' ', 'T') + 'Z';
            }
            d = new Date(s);
        }
        const now = new Date();
        const diffSeconds = Math.floor((now - d) / 1000);
        
        if (diffSeconds < 60) {
            return this.t('time.justNow');
        } else if (diffSeconds < 3600) {
            const minutes = Math.floor(diffSeconds / 60);
            return minutes === 1 
                ? this.t('time.minuteAgo')
                : this.t('time.minutesAgo', { count: minutes });
        } else if (diffSeconds < 86400) {
            const hours = Math.floor(diffSeconds / 3600);
            return hours === 1
                ? this.t('time.hourAgo')
                : this.t('time.hoursAgo', { count: hours });
        } else if (diffSeconds < 604800) {
            const days = Math.floor(diffSeconds / 86400);
            return days === 1
                ? this.t('time.dayAgo')
                : this.t('time.daysAgo', { count: days });
        } else if (diffSeconds < 2592000) {
            const weeks = Math.floor(diffSeconds / 604800);
            return weeks === 1
                ? this.t('time.weekAgo')
                : this.t('time.weeksAgo', { count: weeks });
        } else if (diffSeconds < 31536000) {
            const months = Math.floor(diffSeconds / 2592000);
            return months === 1
                ? this.t('time.monthAgo')
                : this.t('time.monthsAgo', { count: months });
        } else {
            const years = Math.floor(diffSeconds / 31536000);
            return years === 1
                ? this.t('time.yearAgo')
                : this.t('time.yearsAgo', { count: years });
        }
    }
}

// Create global i18n instance
const i18n = new I18n();

// Create a fallback t function immediately
if (typeof window !== 'undefined') {
    // Ensure window.i18n exists with at least a basic t function
    window.i18n = i18n;

    // Translations embedded in the page are used at once (see applyBootstrap).
    if (window.__I18N_BOOTSTRAP) {
        i18n.applyBootstrap(window.__I18N_BOOTSTRAP);
    }
    
    // Add a fallback t function if the class method isn't ready
    if (!window.i18n.t) {
        window.i18n.t = function(key, params) {
            console.warn('i18n.t called before initialization, returning key:', key);
            return key;
        };
    }
}