Translator.php

Go to the documentation of this file.

<?php

namespace Elgg\I18n;

use Elgg\Config;
use Elgg\Includer;
use Elgg\Traits\Loggable;

class Translator {

    use Loggable;
    
    protected array $translations = [];

    protected string $defaultPath;

    protected ?string $current_language = null;

    protected array $allowed_languages;

    protected array $language_paths = [];

    protected bool $was_reloaded = false;

    public function __construct(protected Config $config, protected LocaleService $locale) {
        $this->defaultPath = dirname(__DIR__, 4) . '/languages/';
        
        $this->registerLanguagePath($this->defaultPath);
    }

    public function getLoadedTranslations(): array {
        return $this->translations;
    }

    public function translate(string $message_key, array $args = [], string $language = ''): string {
        if (\Elgg\Values::isEmpty($message_key)) {
            return '';
        }

        // if no language provided, get current language based on detection, user setting or site
        $language = $language ?: $this->getCurrentLanguage();

        // build language array for different trys
        // avoid dupes without overhead of array_unique
        $langs = [
            $language => true,
        ];

        // load site language
        $site_language = $this->config->language;
        if (!empty($site_language)) {
            $langs[$site_language] = true;
        }

        // ultimate language fallback
        $langs['en'] = true;
        
        $langs = array_intersect_key($langs, array_flip($this->getAllowedLanguages()));

        // try to translate
        $string = $message_key;
        foreach (array_keys($langs) as $try_lang) {
            $this->ensureTranslationsLoaded($try_lang);
            
            if (isset($this->translations[$try_lang][$message_key])) {
                $string = $this->translations[$try_lang][$message_key];

                // only pass through if we have arguments to allow backward compatibility
                // with manual sprintf() calls.
                if (!empty($args)) {
                    try {
                        $string = vsprintf($string, $args);
                        
                        if ($string === false) {
                            $string = $message_key;
                            
                            $this->getLogger()->warning("Translation error for key '{$message_key}': Too few arguments provided (" . var_export($args, true) . ')');
                        }
                    } catch (\ValueError $e) {
                        // PHP 8 throws errors
                        $string = $message_key;
                        
                        $this->getLogger()->warning("Translation error for key '{$message_key}': " . $e->getMessage());
                    }
                }

                break;
            } else {
                $message = sprintf(
                    'Missing %s translation for "%s" language key',
                    ($try_lang === 'en') ? 'English' : $try_lang,
                    $message_key
                );
                
                if ($try_lang === 'en') {
                    $this->getLogger()->notice($message);
                } else {
                    $this->getLogger()->info($message);
                }
            }
        }

        return $string;
    }

    public function addTranslation(string $country_code, array $language_array, bool $ensure_translations_loaded = true): bool {
        $country_code = trim(strtolower($country_code));

        if (empty($language_array) || $country_code === '') {
            return false;
        }

        if (!isset($this->translations[$country_code])) {
            $this->translations[$country_code] = [];
            
            if ($ensure_translations_loaded) {
                // make sure all existing paths are included first before adding language arrays
                $this->loadTranslations($country_code);
            }
        }

        // Note that we are using union operator instead of array_merge() due to performance implications
        $this->translations[$country_code] = $language_array + $this->translations[$country_code];

        return true;
    }

    public function getCurrentLanguage(): string {
        if (!isset($this->current_language)) {
            $this->current_language = $this->detectLanguage();
        }

        if (empty($this->current_language)) {
            $this->current_language = 'en';
        }

        return $this->current_language;
    }

    public function setCurrentLanguage(string $language = null): void {
        $this->current_language = $language;
    }

    public function detectLanguage(): string {
        // detect from URL
        $url_lang = _elgg_services()->request->getParam('hl');
        $user = _elgg_services()->session_manager->getLoggedInUser();
        
        if (!empty($url_lang)) {
            // store language for logged out users
            if (empty($user)) {
                $cookie = new \ElggCookie('language');
                $cookie->value = $url_lang;
                elgg_set_cookie($cookie);
            }
            
            return $url_lang;
        }
        
        // detect from cookie
        $cookie = _elgg_services()->request->cookies->get('language');
        if (!empty($cookie)) {
            return $cookie;
        }

        // check logged in user
        if (!empty($user) && !empty($user->language)) {
            return $user->language;
        }

        // detect from browser if not logged in
        if ($this->config->language_detect_from_browser) {
            $browserlangs = _elgg_services()->request->getLanguages();
            if (!empty($browserlangs)) {
                $browserlang = explode('_', $browserlangs[0]);
                
                return $browserlang[0];
            }
        }
        
        // get site setting or empty string if not set in config
        return (string) $this->config->language;
    }

    public function bootTranslations(): void {
        $languages = array_unique(['en', $this->getCurrentLanguage()]);
        
        foreach ($languages as $language) {
            $this->loadTranslations($language);
        }
    }

    public function loadTranslations(string $language): void {
        $data = elgg_load_system_cache("{$language}.lang");
        if (is_array($data)) {
            $this->addTranslation($language, $data, false);
            return;
        }
        
        foreach ($this->getLanguagePaths() as $path) {
            $this->registerTranslations($path, false, $language);
        }
            
        $translations = elgg_extract($language, $this->translations, []);
        elgg_save_system_cache("{$language}.lang", $translations);
    }

    public function registerTranslations(string $path, bool $load_all = false, string $language = null): bool {
        $path = \Elgg\Project\Paths::sanitize($path);
        
        // don't need to register translations as the folder is missing
        if (!is_dir($path)) {
            $this->getLogger()->info("No translations could be loaded from: {$path}");
            return true;
        }

        // Make a note of this path just in case we need to register this language later
        $this->registerLanguagePath($path);

        $this->getLogger()->info("Translations loaded from: {$path}");

        if ($language) {
            $load_language_files = ["{$language}.php"];
            $load_all = false;
        } else {
            // Get the current language based on site defaults and user preference
            $current_language = $this->getCurrentLanguage();

            $load_language_files = [
                'en.php',
                "{$current_language}.php"
            ];

            $load_language_files = array_unique($load_language_files);
        }

        $handle = opendir($path);
        if (empty($handle)) {
            $this->getLogger()->error("Could not open language path: {$path}");
            return false;
        }
        
        $return = true;
        while (($language_file = readdir($handle)) !== false) {
            // ignore bad files
            if (str_starts_with($language_file, '.') || !str_ends_with($language_file, '.php')) {
                continue;
            }

            if (in_array($language_file, $load_language_files) || $load_all) {
                $return = $return && $this->includeLanguageFile($path . $language_file);
            }
        }
        
        closedir($handle);

        return $return;
    }

    protected function includeLanguageFile(string $path): bool {
        $result = Includer::includeFile($path);
        
        if (is_array($result)) {
            $this->addTranslation(basename($path, '.php'), $result);
            return true;
        }
        
        $this->getLogger()->warning("Language file did not return an array: {$path}");
        
        return false;
    }

    public function reloadAllTranslations(): void {
        if ($this->was_reloaded) {
            return;
        }

        $languages = $this->getAvailableLanguages();
        
        foreach ($languages as $language) {
            $this->ensureTranslationsLoaded($language);
        }
        
        _elgg_services()->events->triggerAfter('reload', 'translations');

        $this->was_reloaded = true;
    }

    public function getInstalledTranslations(bool $calculate_completeness = false): array {
        if ($calculate_completeness) {
            // Ensure that all possible translations are loaded
            $this->reloadAllTranslations();
        }
        
        $result = [];

        $languages = $this->getAvailableLanguages();
        foreach ($languages as $language) {
            if ($this->languageKeyExists($language, $language)) {
                $value = $this->translate($language, [], $language);
            } else {
                $value = $this->translate($language);
            }
            
            if (($language !== 'en') && $calculate_completeness) {
                $completeness = $this->getLanguageCompleteness($language);
                $value .= ' (' . $completeness . '% ' . $this->translate('complete') . ')';
            }
            
            $result[$language] = $value;
        }
        
        natcasesort($result);
            
        return $result;
    }

    public function getLanguageCompleteness(string $language): float {
        if ($language === 'en') {
            return (float) 100;
        }

        // Ensure that all possible translations are loaded
        $this->reloadAllTranslations();

        $en = count($this->translations['en']);

        $missing = count($this->getMissingLanguageKeys($language));

        $lang = $en - $missing;

        return round(($lang / $en) * 100, 2);
    }

    public function getMissingLanguageKeys(string $language): array {
        // Ensure that all possible translations are loaded
        $this->reloadAllTranslations();

        $missing = [];

        foreach ($this->translations['en'] as $k => $v) {
            if (!isset($this->translations[$language][$k]) || ($this->translations[$language][$k] === $this->translations['en'][$k])) {
                $missing[] = $k;
            }
        }

        return $missing;
    }

    public function languageKeyExists(string $key, string $language = 'en'): bool {
        if (\Elgg\Values::isEmpty($key)) {
            return false;
        }

        $this->ensureTranslationsLoaded($language);

        if (!array_key_exists($language, $this->translations)) {
            return false;
        }

        return array_key_exists($key, $this->translations[$language]);
    }
    
    public function getAvailableLanguages(): array {
        $languages = [];
        
        $allowed_languages = $this->locale->getLanguageCodes();
        
        foreach ($this->getLanguagePaths() as $path) {
            try {
                $iterator = new \DirectoryIterator($path);
            } catch (\Exception $e) {
                continue;
            }
            
            foreach ($iterator as $file) {
                if ($file->isDir()) {
                    continue;
                }
                
                if ($file->getExtension() !== 'php') {
                    continue;
                }
                
                $language = $file->getBasename('.php');
                if (empty($language) || !in_array($language, $allowed_languages)) {
                    continue;
                }
                
                $languages[$language] = true;
            }
        }
                        
        return _elgg_services()->events->triggerResults('languages', 'translations', [], array_keys($languages));
    }
    
    public function getAllowedLanguages(): array {
        if (isset($this->allowed_languages)) {
            return $this->allowed_languages;
        }
        
        $allowed_languages = $this->config->allowed_languages;
        if (!empty($allowed_languages)) {
            $allowed_languages = explode(',', $allowed_languages);
            $allowed_languages = array_filter(array_unique($allowed_languages));
        } else {
            $allowed_languages = $this->getAvailableLanguages();
        }
        
        if (!in_array($this->config->language, $allowed_languages)) {
            // site language is always allowed
            $allowed_languages[] = $this->config->language;
        }
        
        if (!in_array('en', $allowed_languages)) {
            // 'en' language is always allowed
            $allowed_languages[] = 'en';
        }
        
        $this->allowed_languages = $allowed_languages;
        
        return $allowed_languages;
    }
    
    public function registerLanguagePath(string $path): void {
        if (isset($this->language_paths[$path])) {
            return;
        }
        
        if (!is_dir($path)) {
            return;
        }
        
        $this->language_paths[$path] = true;
    }
    
    public function getLanguagePaths(): array {
        return array_keys($this->language_paths);
    }

    protected function ensureTranslationsLoaded(string $language): void {
        if (isset($this->translations[$language])) {
            return;
        }
        
        // The language being requested is not the same as the language of the
        // logged in user, so we will have to load it separately. (Most likely
        // we're sending a notification and the recipient is using a different
        // language than the logged in user.)
        $this->loadTranslations($language);
    }
}