turbogui-angular 20.6.0 → 20.7.0

package/fesm2022/turbogui-angular.mjs

@@ -1988,7 +1988,7 @@ class RouterBaseService {
      *   { path: '', component: HomePageComponent,
      *     data: { titleKey: 'HOME',  titleBundle: 'turbodepot/user-interface'} },
      *
-     * @param localesService An instance of the LocalesService to be used for translations.
+     * @param localesService An instance of the already initialized LocalesService to be used for translations.
      * @param prefix A text to be added before the computed title.
      * @param sufix A text to be added after the computed title.
      */
@@ -2066,42 +2066,77 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.5", ngImpor
  */
 /**
  * Fully featured translation manager to be used with any application that requires text internationalization.
- * It is defined as an abstract class so it must be extended in our application. This way we can
- * write custom methods to extend the functionality of this class if needed.
+ *
+ * It is designed to load translation bundles from several sources, and then provide methods to translate
+ * any key on any bundle to the desired locale.
+ *
+ * - Provides methods to format the translated text to several case formats like start case, all upper case,
+ * all lower case, first upper rest lower, etc...
+ *
+ * - Provides a way to define wildcards on the translated texts that can be replaced at runtime with custom values.
+ *
+ * The class is designed to be as fast as possible when requesting translations, so it includes an internal memory cache
+ * that will store the results of previous translations and return them directly when the same key is requested again.
+ *
+ * It also includes several configuration options to define how missing keys are handled, what locales are available,
+ * what locales are loaded into memory, what locales are used for translation priority, etc...
+ *
+ * The class does not include any method to load translation bundles from external sources like files or APIs. This is
+ * done on purpose to keep the class as generic as possible and avoid any dependency with external libraries or frameworks.
+ *
+ * It is recommended to use this class as a singleton service in your application, so you can easily access it from
+ * any component or service that requires translation functionalities.
  */
-class LocalesBaseService {
+class TranslationManager {
     constructor() {
         /**
-         * if the class has been correctly initialized and translations have been correctly loaded
+         * This flag defines if the class will allow loading locales that are not defined on the availableLocales list.
+         *
+         * By default this is set to false, so only locales that are defined on the availableLocales list can be loaded.
+         *
+         * If set to true, any locale can be loaded, even if it is not defined on the availableLocales list. In this case,
+         * the locale will be added at the end of the availableLocales list when loaded.
+         *
+         * It is recommended to keep this set to false and always define the availableLocales list before loading any locale,
+         * so we can avoid loading locales that are not supported by our application.
+         *
+         * Notice that this flag does not affect the translation priority list, which must always contain locales that are
+         * defined on the availableLocales list.
+         *
+         * @see setAvailableLocales()
+         * @see setTranslationPriority()
          */
-        this._isInitialized = false;
+        this.isLoadingNonAvaliableLocalesAllowed = false;
         /**
-         * @see getLocales()
+         * @see setTranslationPriority()
          */
-        this._locales = [];
+        this._translationPriority = [];
         /**
-         * @see getLanguages()
+         * @see getLoadedLocales()
          */
-        this._languages = [];
+        this._loadedLocales = [];
         /**
-         * Stores all the loaded localization data by library name, bundle name, key and locales
+         * Stores all the raw localization data that is loaded into memory on this service for all locales.
+         * It is organized like: { library_name: { bundle_name: { locale_code: { key1: "translation1", key2: "translation2" } } } ... }
          */
-        this._loadedTranslations = {};
-        /**
-         * Stores a memory cache to improve performance when outputing translations
-         */
-        this._keyValuesCache = {};
+        this._loadedRawTranslationData = {};
         /**
          * @see setWildCardsFormat()
          */
         this._wildCardsFormat = '{N}';
         /**
-         * @see setMissingKeyFormat()
+         * @see setMissingKeyBehaviour()
          */
-        this._missingKeyFormat = '$exception';
+        this._missingKeyBehaviour = '$exception';
+        /**
+         * Stores a memory cache to improve performance when outputing translations
+         */
+        this._keyValuesCache = {};
         /**
          * Stores a hash value that is used to improve the performance for translation t() methods.
-         * This is computed based on _wildCardsFormat plus _missingKeyFormat plus the current primary locale
+         *
+         * This is computed based on _wildCardsFormat + _missingKeyBehaviour + _translationPriority
+         *
          * Methods that change these values will recalculate the hash string, so when calling translation methods, the
          * performance will be as fast as possible.
          */
@@ -2119,7 +2154,7 @@ class LocalesBaseService {
      *
      * We usually set this before initializing the class translation data
      *
-     * Notice that N is mandayory on the wildcards format and the first index value is 0.
+     * Notice that N is mandatory on the wildcards format and the first index value is 0.
      *
      * @param value The wildcards format we want to set
      *
@@ -2129,7 +2164,7 @@ class LocalesBaseService {
         if (!value.includes('N')) {
             throw new Error("N is mandatory to replace wildcards");
         }
-        this._cacheHashBaseString = value + this._missingKeyFormat + ((this._locales.length > 0) ? this._locales[0] : '');
+        this._cacheHashBaseString = value + this._missingKeyBehaviour + this._translationPriority.join('');
         this._wildCardsFormat = value;
         return value;
     }
@@ -2137,159 +2172,232 @@ class LocalesBaseService {
      * Defines the behaviour for t(), tStartCase(), etc... methods when a key is not found on
      * a bundle or the bundle does not exist
      *
-     * If missingKeyFormat is an empty string, all missing keys will return an empty value (not recommended)
+     * If missingKeyBehaviour is an empty string, all missing keys will return an empty value (not recommended)
      *
-     * If missingKeyFormat contains a string, that string will be always returned for missing keys
+     * If missingKeyBehaviour contains a string, that string will be always returned for missing keys
      *
-     * If missingKeyFormat contains a string with one of the following predefined wildcards:<br>
-     *    - $key will be replaced with key name. Example: get("NAME") will output [NAME] if key is not found and missingKeyFormat = '[$key]'<br>
+     * If missingKeyBehaviour contains a string with one of the following predefined wildcards:<br>
+     *    - $key will be replaced with key name. Example: get("NAME") will output [NAME] if key is not found and missingKeyBehaviour = '[$key]'<br>
      *    - $exception (default value) will throw an exception with the problem cause description.
      *
      * @param value The missing key format we want to set
      *
      * @returns The value that's been set
      */
-    setMissingKeyFormat(value) {
-        this._cacheHashBaseString = this._wildCardsFormat + value + ((this._locales.length > 0) ? this._locales[0] : '');
-        this._missingKeyFormat = value;
+    setMissingKeyBehaviour(value) {
+        this._cacheHashBaseString = this._wildCardsFormat + value + this._translationPriority.join('');
+        this._missingKeyBehaviour = value;
         return value;
     }
     /**
-     * @see setMissingKeyFormat()
+     * @see setMissingKeyBehaviour()
      */
-    getMissingKeyFormat() {
-        return this._missingKeyFormat;
+    getMissingKeyBehaviour() {
+        return this._missingKeyBehaviour;
     }
     /**
      * Adds translations to the class by loading and parsing bundles from the provided JSON object.
-     * After the method finishes, the class will contain all the translation data and will be ready to translate
+     * After the method finishes, the class will contain in memory all the translation data and will be ready to translate
      * any provided key to any of the specified locales.
      *
+     * This method can be called multiple times. New translation data will be merged with any existing data.
+     * If a translation key already exists for a specific library, bundle, and locale, its value will be overwritten by the new data.
+     *
      * @param locales An array of locale codes (e.g., ['en_US', 'es_ES', 'fr_FR']) to load from the json data into this class.
-     *        The order of this array will determine the priority when looking for translations.
+     *        The order of this array is not important for translation priority.
      *
      * @param json A JSON object containing the translation data. The structure must be as follows:
      *       { library_name: { bundle_name: { locale_code: { key1: "translation1", key2: "translation2" } } } ... }
      *
-     * @return True if the translations get correctly loaded. Any unsuccessful initialization will throw an exception
+     * @throws Error If any of the provided locales is not correctly formatted or not defined on the availableLocales
+     *         list or json data does not follow the expected structure.
+     *
+     * @return void
      */
     loadLocalesFromJson(locales, json) {
-        this._isInitialized = false;
+        // Cache must be cleared when loading new translations to ensure all keys are re-evaluated.
+        this._keyValuesCache = {};
         // Validate received locales are correct
         for (const locale of locales) {
             this._validateLocaleString(locale);
+            if (!this.isLoadingNonAvaliableLocalesAllowed &&
+                (!this._availableLocales || !this._availableLocales.includes(locale))) {
+                throw new Error(locale + ' not defined as available for translation');
+            }
         }
         // Validate the translations object follows the right structure
         let isTranslationsValid = false;
+        if (json && typeof json === 'object' && Object.keys(json).length > 0) {
+            for (const library in json) {
+                for (const bundle in json[library]) {
+                    for (const locale in json[library][bundle]) {
+                        this._validateLocaleString(locale);
+                        isTranslationsValid = true;
+                    }
+                }
+            }
+        }
+        if (!isTranslationsValid) {
+            throw new Error('translations must be a non empty object with the structure: { library: { bundle: { xx_XX: { key: translation } } } }');
+        }
+        // Deep merge the new translation data with the existing data.
         for (const library in json) {
+            if (!this._loadedRawTranslationData[library]) {
+                this._loadedRawTranslationData[library] = {};
+            }
             for (const bundle in json[library]) {
+                if (!this._loadedRawTranslationData[library][bundle]) {
+                    this._loadedRawTranslationData[library][bundle] = {};
+                }
                 for (const locale in json[library][bundle]) {
-                    this._validateLocaleString(locale);
-                    isTranslationsValid = true;
+                    if (!this._loadedRawTranslationData[library][bundle][locale]) {
+                        this._loadedRawTranslationData[library][bundle][locale] = {};
+                    }
+                    // Merge the new keys for the locale, overwriting any existing ones.
+                    Object.assign(this._loadedRawTranslationData[library][bundle][locale], json[library][bundle][locale]);
                 }
             }
         }
-        if (!isTranslationsValid) {
-            throw new Error('translations must be a non empty object with the structure: { library: { bundle: { xx_XX: { key: translation } } } }');
+        // Update the list of loaded locales, ensuring no duplicates.
+        this._loadedLocales = Array.from(new Set([...this._loadedLocales, ...locales]));
+        // Add loaded locales to the end of the availableLocales list if they are not already there
+        for (const locale of locales) {
+            if (!this._availableLocales.includes(locale)) {
+                this._availableLocales.push(locale);
+            }
         }
-        this._loadedTranslations = json;
-        this._locales = locales;
-        this._languages = locales.map((l) => l.substring(0, 2));
-        this._cacheHashBaseString = this._wildCardsFormat + this._missingKeyFormat + this._locales[0];
-        this._isInitialized = true;
-        return true;
     }
     /**
-     * Initializes the translation system by loading and parsing bundle files from the specified translations path.
-     * After the promise finishes, the class will contain all the translation data and will be ready to translate any
-     * provided key.
+     * Checks if the specified locale is currently loaded into memory on this service.
      *
-     * @param locales An array of locale codes (['en_US', 'es_ES', 'fr_FR', ...]) to load from the url response.
-     *        The order of this array will determine the translation priority
-     * @param url - Url where the translations are found. The response must be a Json with the expected structure:
-     *              { library_name: { bundle_name: { locale_code: { key1: "translation1", key2: "translation2" } } } ... }
+     * @param locale A locale to check. For example 'en_US'
      *
-     * @return A promise that will resolve if the translations get correctly loaded, or reject with an error if load fails
+     * @return True if the locale is currently loaded on the class, false if not.
      */
-    loadLocalesFromUrl(locales, url) {
-        this._isInitialized = false;
-        return new Promise((resolve, reject) => {
-            fetch(url).then(response => {
-                if (!response.ok) {
-                    throw new Error(`HTTP error! status: ${response.status}`);
-                }
-                return response.json();
-            }).then(data => {
-                this.loadLocalesFromJson(locales, data);
-                resolve(undefined);
-            }).catch(error => {
-                reject(new Error(`ERROR LOADING LOCALES FROM: ${url}\n` + error));
-            });
-        });
+    isLocaleLoaded(locale) {
+        this._validateLocaleString(locale);
+        return this._loadedLocales.includes(locale);
     }
     /**
-     * Check if the class has been correctly initialized and translations have been correctly loaded
+     * Checks if the specified 2 digit language is currently loaded for the currently defined bundles and paths.
+     *
+     * @param language A language to check. For example 'en'
+     *
+     * @return True if the language is currently loaded on the class, false if not.
      */
-    isInitialized() {
-        return this._isInitialized;
+    isLanguageLoaded(language) {
+        this._validateLanguageString(language);
+        return this.getLoadedLanguages().includes(language);
     }
     /**
-     * Aux method to verify that this class is correctly initialized with translation data
+     * @see setAvailableLocales()
      */
-    _validateInitialized() {
-        if (!this._isInitialized) {
-            throw new Error('Translation service not initialized');
-        }
+    getAvailableLocales() {
+        return this._availableLocales;
     }
     /**
-     * Checks if the specified locale is currently loaded for the currently defined bundles and paths.
+     * Define the list of locales that are allowed to be loaded by this class (sorted by preference!).
+     * Each string must be formatted as a standard locale code with language and country joined by an
+     * underscore, like: en_US, fr_FR. The order of this list does matter, so it is better to sort by priority.
      *
-     * @param locale A locale to check. For example 'en_US'
+     * IMPORTANT: This method does not load any locale by itself, it just defines what locales are available for translation.
+     * You also need to load the translation data for the locales to translate texts.
      *
-     * @return True if the locale is currently loaded on the class, false if not.
+     * Before performing any translation, available locales and translation priority must be set, and also translation
+     * data must be loaded for all the locales that are defined on the translation priority list.
+     *
+     * @param locales A list of locales to be set as available for loading
      */
-    isLocaleLoaded(locale) {
-        this._validateLocaleString(locale);
-        return this._locales.includes(locale);
+    setAvailableLocales(locales) {
+        for (const locale of locales) {
+            this._validateLocaleString(locale);
+        }
+        this._availableLocales = locales;
     }
     /**
-     * Aux method to validate that a locale string is correctly formatted
+     * A list containing the locales that have been loaded into memory and ready to be used for translation.
+     * Each string is formatted as a standard locale code with language and country joined by an underscore, like: en_US, fr_FR
      *
-     * @param string $locale A locale string
+     * The order on this list does not matter for translation priority, as that is defined by the translationPriority list.
+     *
+     * @see getLoadedLanguages()
      */
-    _validateLocaleString(locale) {
-        if (!/^[a-z]{2}_[A-Z]{2}$/.test(locale)) {
-            throw new Error('locale must be a valid xx_XX value');
-        }
+    getLoadedLocales() {
+        return this._loadedLocales;
     }
     /**
-     * Checks if the specified 2 digit language is currently loaded for the currently defined bundles and paths.
+     * A list of strings containing the languages have been loaded into memory and ready to be used for translation.
+     * Each string is formatted as a 2 digit language code, like: en, fr
      *
-     * @param language A language to check. For example 'en'
+     * This list is the same as the locales() one, but containing only the language part of each locale (the first two digits)
      *
-     * @return True if the language is currently loaded on the class, false if not.
+     * @see getLoadedLocales()
      */
-    isLanguageLoaded(language) {
-        this._validateLanguageString(language);
-        return this._languages.includes(language);
+    getLoadedLanguages() {
+        return this._loadedLocales.map((l) => l.substring(0, 2));
     }
     /**
-     * Aux method to validate that a language string is correctly formatted
+     * Define the list of locales that will be used for translation priority.
+     * The first locale on the list will be the primary to be used when trying to get a translation, rest will be used
+     * as fallback in the same order as they are defined on this list.
      *
-     * @param language A 2 digit language string
+     * - The list must contain at least one locale and no duplicate elements.
+     * - All locales provided here must exist on the availableLocales list, otherwise an exception will happen.
+     * - When requesting a translation all the locales on this list should be loaded into memory or an exception may happen.
+     * - IMPORTANT: Translation behaviour depends heavily on the missingKeyBehaviour property value.
+     *
+     * @example: After loading the following list of locales ['en_US', 'es_ES', 'fr_FR'] if we call t('HELLO', 'lib1/greetings')
+     *           the localization manager will try to locate the en_US value for the HELLO tag on the greetings bundle for the library lib1.
+     *           If the tag is not found for the specified locale and bundle, the same search will be performed for the es_ES locale, and so, till a
+     *           value is found or no more locales are defined.
+     *
+     * @param localesOrLanguages:string A list of locales (xx_XX) or languages (xx) to be used for translation priority.
+     *
+     * @returns The list of locales that has been set for translation priority
      */
-    _validateLanguageString(language) {
-        if (!/^[a-z]{2}$/.test(language)) {
-            throw new Error('language must be a valid 2 digit value');
+    setTranslationPriority(localesOrLanguages) {
+        // Validate received list is correct
+        if (!Array.isArray(localesOrLanguages) ||
+            (new Set(localesOrLanguages).size !== localesOrLanguages.length) ||
+            localesOrLanguages.length === 0) {
+            throw new Error('locales must be non empty string array with no duplicate elements');
         }
+        const resolvedLocales = [];
+        // Validate all requested locales are available for translation
+        for (const item of localesOrLanguages) {
+            let resolvedLocale = '';
+            if (/^[a-z]{2}$/.test(item)) {
+                resolvedLocale = this._availableLocales.find(l => l.startsWith(item + '_')) ?? '';
+                if (resolvedLocale === '') {
+                    throw new Error(`Language ${item} could not be resolved to any available locale.`);
+                }
+            }
+            else {
+                this._validateLocaleString(item);
+                resolvedLocale = item;
+            }
+            if (!this._availableLocales.includes(resolvedLocale)) {
+                throw new Error(resolvedLocale + ' not defined as available for translation');
+            }
+            resolvedLocales.push(resolvedLocale);
+        }
+        this._translationPriority = resolvedLocales;
+        this._cacheHashBaseString = this._wildCardsFormat + this._missingKeyBehaviour + this._translationPriority.join('');
+        return this._translationPriority;
     }
     /**
-     * Get the translation to the current primary locale for the given key, library and bundle
+     * @see setTranslationPriority()
+     */
+    getTranslationPriority() {
+        return this._translationPriority;
+    }
+    /**
+     * Get a translation based on the current locales translation priority for the given key, library and bundle
      *
      * @param string key The key we want to read from the specified resource bundle
      * @param string bundlePath A string with the format 'library_name/bundle_name' that is used to locate the bundle were the key to translate is found
      * @param array replaceWildcards A list of values that will replace wildcards that may be found on the translated text. Each wildcard
-     *        will be replaced with the element whose index on replaceWildcards matches it. Check the documentation for this.wildCardsFormat
+     *        will be replaced with the element whose index on replaceWildcards matches it. Check the documentation for setWildCardsFormat
      *        property to know more about how to setup wildcards on your translations.
      *
      * @see setWildCardsFormat()
@@ -2297,20 +2405,25 @@ class LocalesBaseService {
      * @return The translated text
      */
     t(key, bundlePath, replaceWildcards = []) {
-        this._validateInitialized();
         // Create a cache key to improve performance when requesting the same key translation several times
         const cacheKey = `${this._cacheHashBaseString}${key}${bundlePath}${replaceWildcards.join('')}`;
         if (!this._keyValuesCache[cacheKey]) {
+            const [library, bundle] = bundlePath.split('/');
             this._forceNonEmptyString(key, '', 'key must be non empty string');
             this._forceNonEmptyString(bundlePath, '', 'bundlePath must be non empty string');
-            const [library, bundle] = bundlePath.split('/');
             this._forceNonEmptyString(library, '', 'no library specified on bundlePath');
             this._forceNonEmptyString(bundle, '', 'no bundle specified on bundlePath');
+            if (this._translationPriority.length === 0) {
+                throw new Error(`No translation priority specified`);
+            }
             const replacementsCount = replaceWildcards.length;
-            // Loop all the locales to find the first one with a value for the specified key
-            for (const locale of this._locales) {
-                if (this._loadedTranslations[library]?.[bundle]?.[locale]?.[key]) {
-                    let result = this._loadedTranslations[library][bundle][locale][key];
+            // Loop all the translation priority locales to find the first one with a value for the specified key
+            for (const locale of this._translationPriority) {
+                if (!this.isLocaleLoaded(locale)) {
+                    throw new Error(`Locale ${locale} must be loaded before requesting translations`);
+                }
+                if (this._loadedRawTranslationData[library]?.[bundle]?.[locale]?.[key]) {
+                    let result = this._loadedRawTranslationData[library][bundle][locale][key];
                     // Replace all wildcards on the text with the specified replacements if any
                     for (let i = 0; i < replacementsCount; i++) {
                         result = this._replace(result, this._replace(this._wildCardsFormat, 'N', i.toString()), replaceWildcards[i]);
@@ -2320,10 +2433,10 @@ class LocalesBaseService {
                 }
             }
             // Check if an exception needs to be thrown if the specified key is not found on this bundle
-            if (this._missingKeyFormat.includes('$exception')) {
+            if (this._missingKeyBehaviour.includes('$exception')) {
                 throw new Error(`Translation key <${key}> not found on <${bundlePath}>`);
             }
-            this._keyValuesCache[cacheKey] = this._replace(this._missingKeyFormat, '$key', key);
+            this._keyValuesCache[cacheKey] = this._replace(this._missingKeyBehaviour, '$key', key);
         }
         return this._keyValuesCache[cacheKey];
     }
@@ -2372,162 +2485,24 @@ class LocalesBaseService {
         return string.charAt(0).toUpperCase() + string.slice(1).toLowerCase();
     }
     /**
-     * A list of strings containing the locales that are used by this class to translate the given keys, sorted by preference.
-     * Each string is formatted as a standard locale code with language and country joined by an underscore, like: en_US, fr_FR
-     *
-     * When a key and bundle are requested for translation, the class will check on the first language of this
-     * list for a translated text. If missing, the next one will be used, and so. This list is constructed after initialize
-     * methods is called.
-     *
-     * @example: After loading the following list of locales ['en_US', 'es_ES', 'fr_FR'] if we call t('HELLO', 'lib1/greetings')
-     * the localization manager will try to locate the en_US value for the HELLO tag on the greetings bundle for the library lib1.
-     * If the tag is not found for the specified locale and bundle, the same search will be performed for the es_ES locale, and so, till a
-     * value is found or no more locales are defined.
-     */
-    getLocales() {
-        return this._locales;
-    }
-    /**
-     * A list of strings containing the languages that are used by this class to translate the given keys, sorted by preference.
-     * Each string is formatted as a 2 digit language code, like: en, fr
-     *
-     * This list is the same as the locales() one, but containing only the language part of each locale (the first two digits)
-     *
-     * @see getLocales()
-     */
-    getLanguages() {
-        return this._languages;
-    }
-    /**
-     * Get the first locale from the list of loaded locales, which is the currently used to search for translated texts.
-     *
-     * @returns The locale that is defined as the primary one. For example: en_US, es_ES, ..
-     */
-    getPrimaryLocale() {
-        this._validateInitialized();
-        return this._locales[0];
-    }
-    /**
-     * Get the first language from the list of loaded locales, which is the currently used to search for translated texts.
-     *
-     * @returns The 2 digit language code that is defined as the primary one. For example: en, es, ..
-     */
-    getPrimaryLanguage() {
-        this._validateInitialized();
-        return this._languages[0];
-    }
-    /**
-     * Define the locale that will be placed at the front of the currently loaded locales list (moving all the others one position to the right).
-     *
-     * This will be the first locale to use when trying to get a translation.
-     *
-     * @param locale A currently loaded locale that will be moved to the first position of the loaded locales list. If the specified locale
-     *        is not currently loaded, an exception will happen.
-     *
-     * @returns void
-     */
-    setPrimaryLocale(locale) {
-        this._validateInitialized();
-        if (!this.isLocaleLoaded(locale)) {
-            throw new Error(locale + ' not loaded');
-        }
-        let result = [locale];
-        for (let l of this._locales) {
-            if (l !== locale) {
-                result.push(l);
-            }
-        }
-        this._locales = result;
-        this._languages = this._locales.map((l) => l.substring(0, 2));
-        this._cacheHashBaseString = this._wildCardsFormat + this._missingKeyFormat + this._locales[0];
-    }
-    /**
-     * Moves the specified locales to the beginning of the locales list. This also alters the translation priority by setting the first
-     * provided locale as the most prioritary, the second as the next one and so.
-     *
-     * This method basically works exactly the same way as setPrimaryLocale but letting us add many locales at once.
-     *
-     * @see setPrimaryLocale()
-     *
-     * @param locales A list of locales to be moved to the beginning of the translation priority. First locales item will be the prefered
-     *        locale for translation, second will be the next one in case some key is not translated for the first one and so. If any of the
-     *        specified locales is not currently loaded, an exception will happen.
-     *
-     * @returns void
-     */
-    setPrimaryLocales(locales) {
-        if (!Array.isArray(locales) ||
-            (new Set(locales).size !== locales.length) ||
-            locales.length === 0) {
-            throw new Error('locales must be non empty string array with no duplicate elements');
-        }
-        for (let i = locales.length - 1; i >= 0; i--) {
-            this.setPrimaryLocale(locales[i]);
-        }
-    }
-    /**
-     * Define the 2 digit language that will be placed at the front of the currently loaded locales list (moving all the others one position to the right).
-     *
-     * This will be the first language to use when trying to get a translation.
-     *
-     * @param language A 2 digit language code that matches with any of the currently loaded locales, which will
-     *        be moved to the first position of the loaded locales list. If the specified language does not match with
-     *        a locale that is currently loaded, an exception will happen.
-     *
-     * @returns void
-     */
-    setPrimaryLanguage(language) {
-        for (let locale of this._locales) {
-            if (locale.substring(0, 2) === language) {
-                this.setPrimaryLocale(locale);
-                return;
-            }
-        }
-        throw new Error(language + ' not loaded');
-    }
-    /**
-     * Moves the locales that match the specified languages to the beginning of the locales list.
-     * Works the same as setPrimaryLocales() but with a list of the 2 digit language codes that match the respective locales.
-     *
-     * @see setPrimaryLocale()
-     * @see setPrimaryLanguage()
-     *
-     * @param languages A list of 2 digit language codes to be moved to the beginning of the translation priority. If any of the
-     *        specified languages does not match with a locale that is currently loaded, an exception will happen.
+     * Aux method to validate that a locale string is correctly formatted
      *
-     * @returns void
+     * @param string $locale A locale string
      */
-    setPrimaryLanguages(languages) {
-        if (!Array.isArray(languages) ||
-            (new Set(languages).size !== languages.length) ||
-            languages.length === 0) {
-            throw new Error('languages must be non empty string array with no duplicate elements');
-        }
-        for (let i = languages.length - 1; i >= 0; i--) {
-            this.setPrimaryLanguage(languages[i]);
+    _validateLocaleString(locale) {
+        if (!/^[a-z]{2}_[A-Z]{2}$/.test(locale)) {
+            throw new Error('locale must be a valid xx_XX value');
         }
     }
     /**
-     * Change the loaded locales translation preference order. The same locales that are currently loaded must be passed
-     * but with a different order to change the translation priority.
-     *
-     * @param locales A list with the new locales translation priority
+     * Aux method to validate that a language string is correctly formatted
      *
-     * @returns void
+     * @param language A 2 digit language string
      */
-    setLocalesOrder(locales) {
-        if (locales.length !== this._locales.length) {
-            throw new Error('locales must contain all the currently loaded locales');
-        }
-        this._validateInitialized();
-        for (let locale of locales) {
-            if (!this.isLocaleLoaded(locale)) {
-                throw new Error(locale + ' not loaded');
-            }
+    _validateLanguageString(language) {
+        if (!/^[a-z]{2}$/.test(language)) {
+            throw new Error('language must be a valid 2 digit value');
         }
-        this._locales = locales;
-        this._languages = this._locales.map((l) => l.substring(0, 2));
-        this._cacheHashBaseString = this._wildCardsFormat + this._missingKeyFormat + this._locales[0];
     }
     /**
      * This is an aux method to implement the TurboCommons StringUtils replace method.
@@ -2540,6 +2515,7 @@ class LocalesBaseService {
     /**
      * This is an aux method to implement the TurboCommons StringUtils isEmpty method.
      * It is exactly the same as the one on the library, but we implement it here to avoid having a dependency with TurboCommons
+     * TODO - If we move this class to TurboCommons, we can remove this method
      */
     _isEmpty(string) {
         let isString = (typeof string === 'string' || string instanceof String);
@@ -2563,7 +2539,108 @@ class LocalesBaseService {
             throw new Error(valueName + ' ' + errorMessage);
         }
     }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.5", ngImport: i0, type: LocalesBaseService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+}
+
+/**
+ * TurboGUI is A library that helps with the most common and generic UI elements and functionalities
+ *
+ * Website : -> http://www.turbogui.org
+ * License : -> Licensed under the Apache License, Version 2.0. You may not use this file except in compliance with the License.
+ * License Url : -> http://www.apache.org/licenses/LICENSE-2.0
+ * CopyRight : -> Copyright 2018 Edertone Advanded Solutions. https://www.edertone.com
+ */
+/**
+ * Fully featured translation service to be used with any application that requires text internationalization.
+ * It is defined as an abstract service class so it must be extended in our application. This way we can
+ * write custom methods to extend the functionality of this class if needed.
+ *
+ * @see TranslationBaseManager for more information about the methods and properties available.
+ */
+class LocalesBaseService extends TranslationManager {
+    constructor() {
+        super(...arguments);
+        /**
+         * Key used to store the user preferred locales in local storage
+         */
+        this._storageKey = 'turbogui-user-translation-priority';
+    }
+    /**
+     * Try to detect the list of locales (sorted by preference) that are defined by the user
+     * at the browser setup and are also available for translation at this class.
+     *
+     * First we will check if there is a stored local storage value that was defined on a previous session.
+     * If found, all the locales stored there that are also available on this class will be returned.
+     *
+     * If no locales could be found from previous sessions, the method will check the browser default language and the
+     * browser languages list. All matching languages that are also listed on availableLocales will be returned, sorted
+     * by the browser preference.
+     *
+     * Finally, if nothing is found, the first locale from the class availableLocales will be returned.
+     *
+     * @returns A list of locales that can be used as a translation priority list
+     */
+    getAvailableLocalesFromBrowser() {
+        if (this._availableLocales.length === 0) {
+            throw new Error('You must define availableLocales before calling detectBrowserLocales()');
+        }
+        let foundLocales = [];
+        // Check for previously stored locales in local storage
+        const storedLocales = localStorage.getItem(this._storageKey);
+        if (storedLocales) {
+            for (const locale of storedLocales.split(',')) {
+                if (this._availableLocales.includes(locale)) {
+                    foundLocales.push(locale);
+                }
+            }
+        }
+        // Check for languages on the current browser setup
+        if (foundLocales.length === 0) {
+            const browserLanguages = navigator.languages || [navigator.language];
+            for (const lang of browserLanguages) {
+                const langCode = lang.split(/[-_]/)[0].toLowerCase();
+                const allowedLocale = this._availableLocales.find(locale => locale.startsWith(langCode + '_'));
+                if (allowedLocale) {
+                    foundLocales.push(allowedLocale);
+                }
+            }
+        }
+        // Return the locales found or the first allowed locale as a fallback
+        return (foundLocales.length > 0) ? foundLocales : [this._availableLocales[0]];
+    }
+    /**
+     * Initializes the translation system by loading and parsing bundle files from the specified translations path.
+     * After the promise finishes, the class will contain all the translation data and will be ready to translate any
+     * provided key.
+     *
+     * @param locales An array of locale codes (['en_US', 'es_ES', 'fr_FR', ...]) to load from the url response.
+     *        The order of this array is not important for translation priority.
+     *
+     * @param url - Url where the translations are found. The response must be a Json with the expected structure:
+     *              { library_name: { bundle_name: { locale_code: { key1: "translation1", key2: "translation2" } } } ... }
+     *
+     * @return A promise that will resolve if the translations get correctly loaded, or reject with an error if load fails
+     */
+    async loadLocalesFromUrl(locales, url) {
+        try {
+            const response = await fetch(url);
+            if (!response.ok) {
+                throw new Error(`HTTP error! status: ${response.status}`);
+            }
+            const data = await response.json();
+            this.loadLocalesFromJson(locales, data);
+        }
+        catch (error) {
+            throw new Error(`ERROR LOADING LOCALES FROM: ${url}\n${error}`);
+        }
+    }
+    setTranslationPriority(localesOrLanguages) {
+        const locales = super.setTranslationPriority(localesOrLanguages);
+        // We override this method to store the user preferred locales in local storage
+        // for future sessions
+        localStorage.setItem(this._storageKey, locales.join(','));
+        return locales;
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.5", ngImport: i0, type: LocalesBaseService, deps: null, target: i0.ɵɵFactoryTarget.Injectable }); }
     static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "19.2.5", ngImport: i0, type: LocalesBaseService, providedIn: 'root' }); }
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.5", ngImport: i0, type: LocalesBaseService, decorators: [{
@@ -2756,11 +2833,11 @@ class DialogSingleSelectionListComponent extends DialogBaseComponent {
         }
     }
     static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.5", ngImport: i0, type: DialogSingleSelectionListComponent, deps: [{ token: i0.ElementRef }, { token: i1.MatDialogRef }, { token: BrowserService }, { token: MAT_DIALOG_DATA }], target: i0.ɵɵFactoryTarget.Component }); }
-    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "19.2.5", type: DialogSingleSelectionListComponent, isStandalone: true, selector: "tg-dialog-single-selection-list", providers: [], usesInheritance: true, ngImport: i0, template: "<h3>\r\n    {{data.texts[0]}}\r\n</h3>\r\n\r\n<!-- Here goes the dialog subtitle. Leave it blank if you don't need it -->\r\n<p *ngIf=\"data.texts.length > 1 &amp;&amp; !stringUtils.isEmpty(data.texts[1])\">\r\n    {{data.texts[1]}}\r\n</p>\r\n\r\n<mat-form-field *ngIf=\"data.texts.length > 2 &amp;&amp; !stringUtils.isEmpty(data.texts[2])\"\r\n    class=\"searchItemInputContainer\">\r\n    \r\n    <mat-label>{{data.texts[2]}}</mat-label>\r\n    <input matInput autoFocusOnDisplay\r\n        (keyup.enter)=\"onIntroKeyPress()\"\r\n        (input)=\"onSearchChange($event.target)\">\r\n        \r\n</mat-form-field>\r\n\r\n<!-- here goes the list of elements that will be shown to the user -->\r\n<div class=\"listItemsContainer\"\r\n    [style.max-height]=\"getListItemsContainerMaxheight()\">\r\n\r\n    <div class=\"listItemContainer\"\r\n        [style.background-color]=\"selectedItemIndex === i ? '#90d1ffad' : (i % 2 === 0 ? 'initial' : '#00000009')\"\r\n        *ngFor=\"let item of filteredOptions; let i = index; trackBy: trackByFn\"\r\n        (click)=\"data.texts.length < 4 ? closeDialog(i) : selectedItemIndex = i\">\r\n    \r\n        <p *ngIf=\"item !== ''\">\r\n            {{item}}\r\n        </p>\r\n    \r\n    </div>\r\n\r\n</div>\r\n\r\n<button mat-raised-button color=\"primary\"\r\n    [disabled]=\"selectedItemIndex < 0\"\r\n    (click)=\"closeDialog(selectedItemIndex)\"\r\n    *ngIf=\"data.texts.length > 3\">\r\n\r\n    {{data.texts[3]}}\r\n    \r\n</button>", styles: [":host{min-height:300px}h3{margin-top:0;margin-bottom:10px}p{margin-top:0;margin-bottom:5px}.searchItemInputContainer{width:100%;margin-top:0;margin-bottom:0}.listItemsContainer{overflow-y:auto;border:1px solid rgba(0,0,0,.2);border-radius:4px;margin-bottom:5px}.listItemContainer p{line-height:36px;width:calc(100% - 12px);margin:0 0 0 6px}button{float:right}\n"], dependencies: [{ kind: "ngmodule", type: CommonModule }, { kind: "directive", type: i2.NgForOf, selector: "[ngFor][ngForOf]", inputs: ["ngForOf", "ngForTrackBy", "ngForTemplate"] }, { kind: "directive", type: i2.NgIf, selector: "[ngIf]", inputs: ["ngIf", "ngIfThen", "ngIfElse"] }, { kind: "ngmodule", type: MatInputModule }, { kind: "directive", type: i4.MatInput, selector: "input[matInput], textarea[matInput], select[matNativeControl],      input[matNativeControl], textarea[matNativeControl]", inputs: ["disabled", "id", "placeholder", "name", "required", "type", "errorStateMatcher", "aria-describedby", "value", "readonly", "disabledInteractive"], exportAs: ["matInput"] }, { kind: "component", type: i4.MatFormField, selector: "mat-form-field", inputs: ["hideRequiredMarker", "color", "floatLabel", "appearance", "subscriptSizing", "hintLabel"], exportAs: ["matFormField"] }, { kind: "directive", type: i4.MatLabel, selector: "mat-label" }, { kind: "ngmodule", type: MatFormFieldModule }, { kind: "ngmodule", type: TurboGuiAngularModule }, { kind: "directive", type: AutoFocusOnDisplayDirective, selector: "[autoFocusOnDisplay]" }] }); }
+    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "19.2.5", type: DialogSingleSelectionListComponent, isStandalone: true, selector: "tg-dialog-single-selection-list", providers: [], usesInheritance: true, ngImport: i0, template: "<h3>\r\n    {{data.texts[0]}}\r\n</h3>\r\n\r\n<!-- Here goes the dialog subtitle. Leave it blank if you don't need it -->\r\n<p *ngIf=\"data.texts.length > 1 &amp;&amp; !stringUtils.isEmpty(data.texts[1])\">\r\n    {{data.texts[1]}}\r\n</p>\r\n\r\n<mat-form-field *ngIf=\"data.texts.length > 2 &amp;&amp; !stringUtils.isEmpty(data.texts[2])\"\r\n    class=\"searchItemInputContainer\">\r\n    \r\n    <mat-label>{{data.texts[2]}}</mat-label>\r\n    <input matInput autoFocusOnDisplay\r\n        (keyup.enter)=\"onIntroKeyPress()\"\r\n        (input)=\"onSearchChange($event.target)\">\r\n        \r\n</mat-form-field>\r\n\r\n<!-- here goes the list of elements that will be shown to the user -->\r\n<div class=\"listItemsContainer\"\r\n    [style.max-height]=\"getListItemsContainerMaxheight()\">\r\n\r\n    <div class=\"listItemContainer\"\r\n        [style.background-color]=\"selectedItemIndex === i ? '#90d1ffad' : (i % 2 === 0 ? 'initial' : '#00000009')\"\r\n        *ngFor=\"let item of filteredOptions; let i = index; trackBy: trackByFn\"\r\n        (click)=\"data.texts.length < 4 ? closeDialog(i) : selectedItemIndex = i\">\r\n    \r\n        <p *ngIf=\"item !== ''\">\r\n            {{item}}\r\n        </p>\r\n    \r\n    </div>\r\n\r\n</div>\r\n\r\n<button mat-raised-button color=\"primary\"\r\n    [disabled]=\"selectedItemIndex < 0\"\r\n    (click)=\"closeDialog(selectedItemIndex)\"\r\n    *ngIf=\"data.texts.length > 3\">\r\n\r\n    {{data.texts[3]}}\r\n    \r\n</button>", styles: [":host{min-height:300px}h3{margin-top:0;margin-bottom:10px}p{margin-top:0;margin-bottom:5px}.searchItemInputContainer{width:100%;margin-top:0;margin-bottom:0}.listItemsContainer{overflow-y:auto;border:1px solid rgba(0,0,0,.2);border-radius:4px;margin-bottom:5px}.listItemContainer p{line-height:36px;width:calc(100% - 12px);margin:0 0 0 6px;cursor:pointer}button{float:right}\n"], dependencies: [{ kind: "ngmodule", type: CommonModule }, { kind: "directive", type: i2.NgForOf, selector: "[ngFor][ngForOf]", inputs: ["ngForOf", "ngForTrackBy", "ngForTemplate"] }, { kind: "directive", type: i2.NgIf, selector: "[ngIf]", inputs: ["ngIf", "ngIfThen", "ngIfElse"] }, { kind: "ngmodule", type: MatInputModule }, { kind: "directive", type: i4.MatInput, selector: "input[matInput], textarea[matInput], select[matNativeControl],      input[matNativeControl], textarea[matNativeControl]", inputs: ["disabled", "id", "placeholder", "name", "required", "type", "errorStateMatcher", "aria-describedby", "value", "readonly", "disabledInteractive"], exportAs: ["matInput"] }, { kind: "component", type: i4.MatFormField, selector: "mat-form-field", inputs: ["hideRequiredMarker", "color", "floatLabel", "appearance", "subscriptSizing", "hintLabel"], exportAs: ["matFormField"] }, { kind: "directive", type: i4.MatLabel, selector: "mat-label" }, { kind: "ngmodule", type: MatFormFieldModule }, { kind: "ngmodule", type: TurboGuiAngularModule }, { kind: "directive", type: AutoFocusOnDisplayDirective, selector: "[autoFocusOnDisplay]" }] }); }
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.5", ngImport: i0, type: DialogSingleSelectionListComponent, decorators: [{
             type: Component,
-            args: [{ selector: 'tg-dialog-single-selection-list', imports: [CommonModule, MatInputModule, MatFormFieldModule, TurboGuiAngularModule], providers: [], template: "<h3>\r\n    {{data.texts[0]}}\r\n</h3>\r\n\r\n<!-- Here goes the dialog subtitle. Leave it blank if you don't need it -->\r\n<p *ngIf=\"data.texts.length > 1 &amp;&amp; !stringUtils.isEmpty(data.texts[1])\">\r\n    {{data.texts[1]}}\r\n</p>\r\n\r\n<mat-form-field *ngIf=\"data.texts.length > 2 &amp;&amp; !stringUtils.isEmpty(data.texts[2])\"\r\n    class=\"searchItemInputContainer\">\r\n    \r\n    <mat-label>{{data.texts[2]}}</mat-label>\r\n    <input matInput autoFocusOnDisplay\r\n        (keyup.enter)=\"onIntroKeyPress()\"\r\n        (input)=\"onSearchChange($event.target)\">\r\n        \r\n</mat-form-field>\r\n\r\n<!-- here goes the list of elements that will be shown to the user -->\r\n<div class=\"listItemsContainer\"\r\n    [style.max-height]=\"getListItemsContainerMaxheight()\">\r\n\r\n    <div class=\"listItemContainer\"\r\n        [style.background-color]=\"selectedItemIndex === i ? '#90d1ffad' : (i % 2 === 0 ? 'initial' : '#00000009')\"\r\n        *ngFor=\"let item of filteredOptions; let i = index; trackBy: trackByFn\"\r\n        (click)=\"data.texts.length < 4 ? closeDialog(i) : selectedItemIndex = i\">\r\n    \r\n        <p *ngIf=\"item !== ''\">\r\n            {{item}}\r\n        </p>\r\n    \r\n    </div>\r\n\r\n</div>\r\n\r\n<button mat-raised-button color=\"primary\"\r\n    [disabled]=\"selectedItemIndex < 0\"\r\n    (click)=\"closeDialog(selectedItemIndex)\"\r\n    *ngIf=\"data.texts.length > 3\">\r\n\r\n    {{data.texts[3]}}\r\n    \r\n</button>", styles: [":host{min-height:300px}h3{margin-top:0;margin-bottom:10px}p{margin-top:0;margin-bottom:5px}.searchItemInputContainer{width:100%;margin-top:0;margin-bottom:0}.listItemsContainer{overflow-y:auto;border:1px solid rgba(0,0,0,.2);border-radius:4px;margin-bottom:5px}.listItemContainer p{line-height:36px;width:calc(100% - 12px);margin:0 0 0 6px}button{float:right}\n"] }]
+            args: [{ selector: 'tg-dialog-single-selection-list', imports: [CommonModule, MatInputModule, MatFormFieldModule, TurboGuiAngularModule], providers: [], template: "<h3>\r\n    {{data.texts[0]}}\r\n</h3>\r\n\r\n<!-- Here goes the dialog subtitle. Leave it blank if you don't need it -->\r\n<p *ngIf=\"data.texts.length > 1 &amp;&amp; !stringUtils.isEmpty(data.texts[1])\">\r\n    {{data.texts[1]}}\r\n</p>\r\n\r\n<mat-form-field *ngIf=\"data.texts.length > 2 &amp;&amp; !stringUtils.isEmpty(data.texts[2])\"\r\n    class=\"searchItemInputContainer\">\r\n    \r\n    <mat-label>{{data.texts[2]}}</mat-label>\r\n    <input matInput autoFocusOnDisplay\r\n        (keyup.enter)=\"onIntroKeyPress()\"\r\n        (input)=\"onSearchChange($event.target)\">\r\n        \r\n</mat-form-field>\r\n\r\n<!-- here goes the list of elements that will be shown to the user -->\r\n<div class=\"listItemsContainer\"\r\n    [style.max-height]=\"getListItemsContainerMaxheight()\">\r\n\r\n    <div class=\"listItemContainer\"\r\n        [style.background-color]=\"selectedItemIndex === i ? '#90d1ffad' : (i % 2 === 0 ? 'initial' : '#00000009')\"\r\n        *ngFor=\"let item of filteredOptions; let i = index; trackBy: trackByFn\"\r\n        (click)=\"data.texts.length < 4 ? closeDialog(i) : selectedItemIndex = i\">\r\n    \r\n        <p *ngIf=\"item !== ''\">\r\n            {{item}}\r\n        </p>\r\n    \r\n    </div>\r\n\r\n</div>\r\n\r\n<button mat-raised-button color=\"primary\"\r\n    [disabled]=\"selectedItemIndex < 0\"\r\n    (click)=\"closeDialog(selectedItemIndex)\"\r\n    *ngIf=\"data.texts.length > 3\">\r\n\r\n    {{data.texts[3]}}\r\n    \r\n</button>", styles: [":host{min-height:300px}h3{margin-top:0;margin-bottom:10px}p{margin-top:0;margin-bottom:5px}.searchItemInputContainer{width:100%;margin-top:0;margin-bottom:0}.listItemsContainer{overflow-y:auto;border:1px solid rgba(0,0,0,.2);border-radius:4px;margin-bottom:5px}.listItemContainer p{line-height:36px;width:calc(100% - 12px);margin:0 0 0 6px;cursor:pointer}button{float:right}\n"] }]
         }], ctorParameters: () => [{ type: i0.ElementRef }, { type: i1.MatDialogRef }, { type: BrowserService }, { type: undefined, decorators: [{
                     type: Inject,
                     args: [MAT_DIALOG_DATA]