#

API Docs for: 3.10.3
Show: Inherited Protected Private Deprecated

# File: intl/js/Intl.js

    var _mods = {},

        ROOT_LANG = "yuiRootLang",
        ACTIVE_LANG = "yuiActiveLang",
        NONE = [];

    /**
     * Provides utilities to support the management of localized resources (strings and formatting patterns).
     *
     * @module intl
     */

    /**
     * The Intl utility provides a central location for managing sets of localized resources (strings and formatting patterns).
     *
     * @class Intl
     * @uses EventTarget
     * @static
     */
    Y.mix(Y.namespace("Intl"), {

        /**
         * Private method to retrieve the language hash for a given module.
         *
         * @method _mod
         * @private
         *
         * @param {String} module The name of the module
         * @return {Object} The hash of localized resources for the module, keyed by BCP language tag
         */
        _mod : function(module) {
            if (!_mods[module]) {
                _mods[module] = {};
            }
            return _mods[module];
        },

        /**
         * Sets the active language for the given module.
         *
         * Returns false on failure, which would happen if the language had not been registered through the <a href="#method_add">add()</a> method.
         *
         * @method setLang
         *
         * @param {String} module The module name.
         * @param {String} lang The BCP 47 language tag.
         * @return boolean true if successful, false if not.
         */
        setLang : function(module, lang) {
            var langs = this._mod(module),
                currLang = langs[ACTIVE_LANG],
                exists = !!langs[lang];

            if (exists && lang !== currLang) {
                langs[ACTIVE_LANG] = lang;
                this.fire("intl:langChange", {module: module, prevVal: currLang, newVal: (lang === ROOT_LANG) ? "" : lang});
            }

            return exists;
        },

        /**
         * Get the currently active language for the given module.
         *
         * @method getLang
         *
         * @param {String} module The module name.
         * @return {String} The BCP 47 language tag.
         */
        getLang : function(module) {
            var lang = this._mod(module)[ACTIVE_LANG];
            return (lang === ROOT_LANG) ? "" : lang;
        },

        /**
         * Register a hash of localized resources for the given module and language
         *
         * @method add
         *
         * @param {String} module The module name.
         * @param {String} lang The BCP 47 language tag.
         * @param {Object} strings The hash of localized values, keyed by the string name.
         */
        add : function(module, lang, strings) {
            lang = lang || ROOT_LANG;
            this._mod(module)[lang] = strings;
            this.setLang(module, lang);
        },

        /**
         * Gets the module's localized resources for the currently active language (as provided by the <a href="#method_getLang">getLang</a> method).
         * <p>
         * Optionally, the localized resources for alternate languages which have been added to Intl (see the <a href="#method_add">add</a> method) can
         * be retrieved by providing the BCP 47 language tag as the lang parameter.
         * </p>
         * @method get
         *
         * @param {String} module The module name.
         * @param {String} key Optional. A single resource key. If not provided, returns a copy (shallow clone) of all resources.
         * @param {String} lang Optional. The BCP 47 language tag. If not provided, the module's currently active language is used.
         * @return String | Object A copy of the module's localized resources, or a single value if key is provided.
         */
        get : function(module, key, lang) {
            var mod = this._mod(module),
                strs;

            lang = lang || mod[ACTIVE_LANG];
            strs = mod[lang] || {};

            return (key) ? strs[key] : Y.merge(strs);
        },

        /**
         * Gets the list of languages for which localized resources are available for a given module, based on the module
         * meta-data (part of loader). If loader is not on the page, returns an empty array.
         *
         * @method getAvailableLangs
         * @param {String} module The name of the module
         * @return {Array} The array of languages available.
         */
        getAvailableLangs : function(module) {
            var loader = Y.Env._loader,
                mod = loader && loader.moduleInfo[module],
                langs = mod && mod.lang;
            return (langs) ? langs.concat() : NONE;

        }
    });

    Y.augment(Y.Intl, Y.EventTarget);

    /**
     * Notification event to indicate when the lang for a module has changed. There is no default behavior associated with this event,
     * so the on and after moments are equivalent.
     *
     * @event intl:langChange
     * @param {EventFacade} e The event facade
     * <p>The event facade contains:</p>
     * <dl>
     *     <dt>module</dt><dd>The name of the module for which the language changed</dd>
     *     <dt>newVal</dt><dd>The new language tag</dd>
     *     <dt>prevVal</dt><dd>The current language tag</dd>
     * </dl>
     */
    Y.Intl.publish("intl:langChange", {emitFacade:true});