turbogui-angular/main/controller/locales-base.service.d.ts

A library that tries to help with the most common user interface elements on several frameworks and platforms

import * as i0 from "@angular/core";
/**
 * 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.
 */
export declare abstract class LocalesBaseService {
    /**
     * if the class has been correctly initialized and translations have been correctly loaded
     */
    private _isInitialized;
    /**
     * @see getLocales()
     */
    private _locales;
    /**
     * @see getLanguages()
     */
    private _languages;
    /**
     * Stores all the loaded localization data by library name, bundle name, key and locales
     */
    private _loadedTranslations;
    /**
     * Stores a memory cache to improve performance when outputing translations
     */
    private _keyValuesCache;
    /**
     * @see setWildCardsFormat()
     */
    private _wildCardsFormat;
    /**
     * @see setMissingKeyFormat()
     */
    private _missingKeyFormat;
    /**
     * 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
     * Methods that change these values will recalculate the hash string, so when calling translation methods, the
     * performance will be as fast as possible.
     */
    private _cacheHashBaseString;
    /**
     * Wildcards are string fragments that are placed inside the translated texts. Their main purpose is to be replaced at
     * runtime by custom values like for example a user name, a date, a numeric value, etc..
     *
     * This class helps with this process by including a parameter called 'toReplace' on all ->t methods which allows us
     * to specify a string or list of strings that will replace the respective wildcards on the translated text. Each wildcard
     * must follow the format specified here, and contain a numeric digit that will be used to find the replacement text at the
     * 'toReplace' list. For example, if we define $N as the wildcard format, and we have a translation that contains $0, $1, $2,
     * $0 will be replaced with the first element on toReplace, $1 with the second and so.
     *
     * 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.
     *
     * @param value The wildcards format we want to set
     *
     * @returns The value that's been set
     */
    setWildCardsFormat(value: string): string;
    /**
     * 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 missingKeyFormat 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>
     *    - $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: string): string;
    /**
     * @see setMissingKeyFormat()
     */
    getMissingKeyFormat(): string;
    /**
     * 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
     * any provided key to any of the specified locales.
     *
     * @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.
     *
     * @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
     */
    loadLocalesFromJson(locales: string[], json: any): boolean;
    /**
     * 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 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" } } } ... }
     *
     * @return A promise that will resolve if the translations get correctly loaded, or reject with an error if load fails
     */
    loadLocalesFromUrl(locales: string[], url: string): Promise<unknown>;
    /**
     * Check if the class has been correctly initialized and translations have been correctly loaded
     */
    isInitialized(): boolean;
    /**
     * Aux method to verify that this class is correctly initialized with translation data
     */
    private _validateInitialized;
    /**
     * Checks if the specified locale is currently loaded for the currently defined bundles and paths.
     *
     * @param locale A locale to check. For example 'en_US'
     *
     * @return True if the locale is currently loaded on the class, false if not.
     */
    isLocaleLoaded(locale: string): boolean;
    /**
     * Aux method to validate that a locale string is correctly formatted
     *
     * @param string $locale A locale string
     */
    private _validateLocaleString;
    /**
     * 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.
     */
    isLanguageLoaded(language: string): boolean;
    /**
     * Aux method to validate that a language string is correctly formatted
     *
     * @param language A 2 digit language string
     */
    _validateLanguageString(language: string): void;
    /**
     * Get the translation to the current primary locale 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
     *        property to know more about how to setup wildcards on your translations.
     *
     * @see setWildCardsFormat()
     *
     * @return The translated text
     */
    t(key: string, bundlePath: string, replaceWildcards?: string[]): any;
    /**
     * Get the translation for the given key and bundle as a string with all words first character capitalized
     * and all the rest of the word with lower case
     *
     * @see t()
     *
     * @returns The localized and case formatted text
     */
    tStartCase(key: string, bundlePath: string, replaceWildcards?: string[]): any;
    /**
     * Get the translation for the given key and bundle as an all upper case string
     *
     * @see t()
     *
     * @returns The localized and case formatted text
     */
    tAllUpperCase(key: string, bundlePath: string, replaceWildcards?: string[]): any;
    /**
     * Get the translation for the given key and bundle as an all lower case string
     *
     * @see t()
     *
     * @returns The localized and case formatted text
     */
    tAllLowerCase(key: string, bundlePath: string, replaceWildcards?: string[]): any;
    /**
     * Get the translation for the given key and bundle as a string with the first character as Upper case
     * and all the rest as lower case
     *
     * @see t()
     *
     * @returns The localized and case formatted text
     */
    tFirstUpperRestLower(key: string, bundlePath: string, replaceWildcards?: string[]): any;
    /**
     * 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(): string[];
    /**
     * 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(): string[];
    /**
     * 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(): string;
    /**
     * 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(): string;
    /**
     * 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: string): void;
    /**
     * 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: string[]): void;
    /**
     * 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: string): void;
    /**
     * 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.
     *
     * @returns void
     */
    setPrimaryLanguages(languages: string[]): void;
    /**
     * 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
     *
     * @returns void
     */
    setLocalesOrder(locales: string[]): void;
    /**
     * This is an aux method to implement the TurboCommons StringUtils replace method.
     * It is exactly the same as the one on the library, but we implement it here to avoid having a dependency with TurboCommons
     */
    private _replace;
    /**
     * 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
     */
    private _isEmpty;
    /**
     * This is an aux method to implement the TurboCommons StringUtils forceNonEmptyString method.
     * It is exactly the same as the one on the library, but we implement it here to avoid having a dependency with TurboCommons
     */
    private _forceNonEmptyString;
    static ɵfac: i0.ɵɵFactoryDeclaration<LocalesBaseService, never>;
    static ɵprov: i0.ɵɵInjectableDeclaration<LocalesBaseService>;
}
//# sourceMappingURL=locales-base.service.d.ts.map