3 Copyright 2012 Yahoo! Inc. All rights reserved.
4 Licensed under the BSD License.
5 http://yuilibrary.com/license/
7 YUI.add('intl', function(Y) {
11 ROOT_LANG = "yuiRootLang",
12 ACTIVE_LANG = "yuiActiveLang",
16 * Provides utilities to support the management of localized resources (strings and formatting patterns).
22 * The Intl utility provides a central location for managing sets of localized resources (strings and formatting patterns).
28 Y.mix(Y.namespace("Intl"), {
31 * Private method to retrieve the language hash for a given module.
36 * @param {String} module The name of the module
37 * @return {Object} The hash of localized resources for the module, keyed by BCP language tag
39 _mod : function(module) {
47 * Sets the active language for the given module.
49 * Returns false on failure, which would happen if the language had not been registered through the <a href="#method_add">add()</a> method.
53 * @param {String} module The module name.
54 * @param {String} lang The BCP 47 language tag.
55 * @return boolean true if successful, false if not.
57 setLang : function(module, lang) {
58 var langs = this._mod(module),
59 currLang = langs[ACTIVE_LANG],
60 exists = !!langs[lang];
62 if (exists && lang !== currLang) {
63 langs[ACTIVE_LANG] = lang;
64 this.fire("intl:langChange", {module: module, prevVal: currLang, newVal: (lang === ROOT_LANG) ? "" : lang});
71 * Get the currently active language for the given module.
75 * @param {String} module The module name.
76 * @return {String} The BCP 47 language tag.
78 getLang : function(module) {
79 var lang = this._mod(module)[ACTIVE_LANG];
80 return (lang === ROOT_LANG) ? "" : lang;
84 * Register a hash of localized resources for the given module and language
88 * @param {String} module The module name.
89 * @param {String} lang The BCP 47 language tag.
90 * @param {Object} strings The hash of localized values, keyed by the string name.
92 add : function(module, lang, strings) {
93 lang = lang || ROOT_LANG;
94 this._mod(module)[lang] = strings;
95 this.setLang(module, lang);
99 * Gets the module's localized resources for the currently active language (as provided by the <a href="#method_getLang">getLang</a> method).
101 * Optionally, the localized resources for alternate languages which have been added to Intl (see the <a href="#method_add">add</a> method) can
102 * be retrieved by providing the BCP 47 language tag as the lang parameter.
106 * @param {String} module The module name.
107 * @param {String} key Optional. A single resource key. If not provided, returns a copy (shallow clone) of all resources.
108 * @param {String} lang Optional. The BCP 47 language tag. If not provided, the module's currently active language is used.
109 * @return String | Object A copy of the module's localized resources, or a single value if key is provided.
111 get : function(module, key, lang) {
112 var mod = this._mod(module),
115 lang = lang || mod[ACTIVE_LANG];
116 strs = mod[lang] || {};
118 return (key) ? strs[key] : Y.merge(strs);
122 * Gets the list of languages for which localized resources are available for a given module, based on the module
123 * meta-data (part of loader). If loader is not on the page, returns an empty array.
125 * @method getAvailableLangs
126 * @param {String} module The name of the module
127 * @return {Array} The array of languages available.
129 getAvailableLangs : function(module) {
130 var loader = Y.Env._loader,
131 mod = loader && loader.moduleInfo[module],
132 langs = mod && mod.lang;
133 return (langs) ? langs.concat() : NONE;
138 Y.augment(Y.Intl, Y.EventTarget);
141 * Notification event to indicate when the lang for a module has changed. There is no default behavior associated with this event,
142 * so the on and after moments are equivalent.
144 * @event intl:langChange
145 * @param {EventFacade} e The event facade
146 * <p>The event facade contains:</p>
148 * <dt>module</dt><dd>The name of the module for which the language changed</dd>
149 * <dt>newVal</dt><dd>The new language tag</dd>
150 * <dt>prevVal</dt><dd>The current language tag</dd>
153 Y.Intl.publish("intl:langChange", {emitFacade:true});
156 }, '3.5.0' ,{requires:['event-custom', 'intl-base']});