jssource/src_files/include/javascript/yui3/build/intl/intl.js

   1 /*
   2 Copyright (c) 2010, Yahoo! Inc. All rights reserved.
   3 Code licensed under the BSD License:
   4 http://developer.yahoo.com/yui/license.html
   5 version: 3.3.0
   6 build: 3167
   7 */
   8 YUI.add('intl', function(Y) {
   9
  10 var _mods = {},
  11
  12     ROOT_LANG = "yuiRootLang",
  13     ACTIVE_LANG = "yuiActiveLang",
  14     NONE = [];
  15
  16 /**
  17  * Provides utilities to support the management of localized resources (strings and formatting patterns).
  18  *
  19  * @module intl
  20  */
  21
  22 /**
  23  * The Intl utility provides a central location for managing sets of localized resources (strings and formatting patterns).
  24  *
  25  * @class Intl
  26  * @uses EventTarget
  27  * @static
  28  */
  29 Y.mix(Y.namespace("Intl"), {
  30
  31     /**
  32      * Private method to retrieve the language hash for a given module.
  33      *
  34      * @method _mod
  35      * @private
  36      *
  37      * @param {String} module The name of the module
  38      * @return {Object} The hash of localized resources for the module, keyed by BCP language tag
  39      */
  40     _mod : function(module) {
  41         if (!_mods[module]) {
  42             _mods[module] = {};
  43         }
  44         return _mods[module];
  45     },
  46
  47     /**
  48      * Sets the active language for the given module.
  49      *
  50      * Returns false on failure, which would happen if the language had not been registered through the <a href="#method_add">add()</a> method.
  51      *
  52      * @method setLang
  53      *
  54      * @param {String} module The module name.
  55      * @param {String} lang The BCP 47 language tag.
  56      * @return boolean true if successful, false if not.
  57      */
  58     setLang : function(module, lang) {
  59         var langs = this._mod(module),
  60             currLang = langs[ACTIVE_LANG],
  61             exists = !!langs[lang];
  62
  63         if (exists && lang !== currLang) {
  64             langs[ACTIVE_LANG] = lang;
  65             this.fire("intl:langChange", {module: module, prevVal: currLang, newVal: (lang === ROOT_LANG) ? "" : lang});
  66         }
  67
  68         return exists;
  69     },
  70
  71     /**
  72      * Get the currently active language for the given module.
  73      *
  74      * @method getLang
  75      *
  76      * @param {String} module The module name.
  77      * @return {String} The BCP 47 language tag.
  78      */
  79     getLang : function(module) {
  80         var lang = this._mod(module)[ACTIVE_LANG];
  81         return (lang === ROOT_LANG) ? "" : lang;
  82     },
  83
  84     /**
  85      * Register a hash of localized resources for the given module and language
  86      *
  87      * @method add
  88      *
  89      * @param {String} module The module name.
  90      * @param {String} lang The BCP 47 language tag.
  91      * @param {Object} strings The hash of localized values, keyed by the string name.
  92      */
  93     add : function(module, lang, strings) {
  94         lang = lang || ROOT_LANG;
  95         this._mod(module)[lang] = strings;
  96         this.setLang(module, lang);
  97     },
  98
  99     /**
 100      * Gets the module's localized resources for the currently active language (as provided by the <a href="#method_getLang">getLang</a> method).
 101      * <p>
 102      * Optionally, the localized resources for alternate languages which have been added to Intl (see the <a href="#method_add">add</a> method) can
 103      * be retrieved by providing the BCP 47 language tag as the lang parameter.
 104      * </p>
 105      * @method get
 106      *
 107      * @param {String} module The module name.
 108      * @param {String} key Optional. A single resource key. If not provided, returns a copy (shallow clone) of all resources.
 109      * @param {String} lang Optional. The BCP 47 language tag. If not provided, the module's currently active language is used.
 110      * @return String | Object A copy of the module's localized resources, or a single value if key is provided.
 111      */
 112     get : function(module, key, lang) {
 113         var mod = this._mod(module),
 114             strs;
 115
 116         lang = lang || mod[ACTIVE_LANG];
 117         strs = mod[lang] || {};
 118
 119         return (key) ? strs[key] : Y.merge(strs);
 120     },
 121
 122     /**
 123      * Gets the list of languages for which localized resources are available for a given module, based on the module
 124      * meta-data (part of loader). If loader is not on the page, returns an empty array.
 125      *
 126      * @method getAvailableLangs
 127      * @param {String} module The name of the module
 128      * @return {Array} The array of languages available.
 129      */
 130     getAvailableLangs : function(module) {
 131         var loader = Y.Env._loader,
 132             mod = loader && loader.moduleInfo[module],
 133             langs = mod && mod.lang;
 134         return (langs) ? langs.concat() : NONE;
 135
 136     }
 137 });
 138
 139 Y.augment(Y.Intl, Y.EventTarget);
 140
 141 /**
 142  * Notification event to indicate when the lang for a module has changed. There is no default behavior associated with this event,
 143  * so the on and after moments are equivalent.
 144  *
 145  * @event intl:langChange
 146  * @param {EventFacade} e The event facade
 147  * <p>The event facade contains:</p>
 148  * <dl>
 149  *     <dt>module</dt><dd>The name of the module for which the language changed</dd>
 150  *     <dt>newVal</dt><dd>The new language tag</dd>
 151  *     <dt>prevVal</dt><dd>The current language tag</dd>
 152  * </dl>
 153  */
 154 Y.Intl.publish("intl:langChange", {emitFacade:true});
 155
 156
 157 }, '3.3.0' ,{requires:['event-custom']});