1 /* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5 this.EXPORTED_SYMBOLS = ["StringBundle"];
7 const {classes: Cc, interfaces: Ci, results: Cr, utils: Cu} = Components;
12 * This object presents two APIs: a deprecated one that is equivalent to the API
13 * for the stringbundle XBL binding, to make it easy to switch from that binding
14 * to this module, and a new one that is simpler and easier to use.
16 * The benefit of this module over the XBL binding is that it can also be used
17 * in JavaScript modules and components, not only in chrome JS.
19 * To use this module, import it, create a new instance of StringBundle,
20 * and then use the instance's |get| and |getAll| methods to retrieve strings
21 * (you can get both plain and formatted strings with |get|):
24 * new StringBundle("chrome://example/locale/strings.properties");
25 * let foo = strings.get("foo");
26 * let barFormatted = strings.get("bar", [arg1, arg2]);
27 * for each (let string in strings.getAll())
28 * dump (string.key + " = " + string.value + "\n");
31 * the URL of the string bundle
33 this.StringBundle = function StringBundle(url) {
37 StringBundle.prototype = {
39 * the locale associated with the application
45 return Cc["@mozilla.org/intl/nslocaleservice;1"].
46 getService(Ci.nsILocaleService).
47 getApplicationLocale();
55 * the wrapped nsIStringBundle
56 * @type nsIStringBundle
60 let stringBundle = Cc["@mozilla.org/intl/stringbundle;1"].
61 getService(Ci.nsIStringBundleService).
62 createBundle(this.url, this._appLocale);
63 this.__defineGetter__("_stringBundle", function() stringBundle);
64 return this._stringBundle;
71 * the URL of the string bundle
80 delete this._stringBundle;
84 * Get a string from the bundle.
87 * the identifier of the string to get
88 * @param args {array} [optional]
89 * an array of arguments that replace occurrences of %S in the string
91 * @returns {String} the value of the string
93 get: function(key, args) {
95 return this.stringBundle.formatStringFromName(key, args, args.length);
97 return this.stringBundle.GetStringFromName(key);
101 * Get all the strings in the bundle.
104 * an array of objects with key and value properties
109 // FIXME: for performance, return an enumerable array that wraps the string
110 // bundle's nsISimpleEnumerator (does JavaScript already support this?).
112 let enumerator = this.stringBundle.getSimpleEnumeration();
114 while (enumerator.hasMoreElements()) {
115 // We could simply return the nsIPropertyElement objects, but I think
116 // it's better to return standard JS objects that behave as consumers
117 // expect JS objects to behave (f.e. you can modify them dynamically).
118 let string = enumerator.getNext().QueryInterface(Ci.nsIPropertyElement);
119 strings.push({ key: string.key, value: string.value });
126 // the deprecated XBL binding-compatible API
129 * the URL of the string bundle
130 * @deprecated because its name doesn't make sense outside of an XBL binding
141 * the locale associated with the application
142 * @deprecated because it has never been used outside the XBL binding itself,
143 * and consumers should obtain it directly from the locale service anyway.
147 return this._appLocale;
151 * the wrapped nsIStringBundle
152 * @deprecated because this module should provide all necessary functionality
153 * @type nsIStringBundle
155 * If you do ever need to use this, let the authors of this module know why
156 * so they can surface functionality for your use case in the module itself
157 * and you don't have to access this underlying XPCOM component.
160 return this._stringBundle;
164 * Get a string from the bundle.
165 * @deprecated use |get| instead
167 * @param key {String}
168 * the identifier of the string to get
171 * the value of the string
173 getString: function(key) {
174 return this.get(key);
178 * Get a formatted string from the bundle.
179 * @deprecated use |get| instead
181 * @param key {string}
182 * the identifier of the string to get
183 * @param args {array}
184 * an array of arguments that replace occurrences of %S in the string
187 * the formatted value of the string
189 getFormattedString: function(key, args) {
190 return this.get(key, args);
194 * Get an enumeration of the strings in the bundle.
195 * @deprecated use |getAll| instead
197 * @returns {nsISimpleEnumerator}
198 * a enumeration of the strings in the bundle
201 return this.stringBundle.getSimpleEnumeration();