If the first argument in the array is an {@link Integer}
* object, a translation will be selected accounting for plurality in
* the following manner. Assume a message key of
* m.widgets, the following translations should be
* defined:
*
* m.widgets.0 = no widgets.
* m.widgets.1 = {0} widget.
* m.widgets.n = {0} widgets.
*
*
* The specified argument is substituted into the translated string as
* appropriate. Consider using:
*
*
* m.widgets.n = {0,number,integer} widgets.
*
*
* to obtain proper insertion of commas and dots as appropriate for
* the locale.
*
* See {@link MessageFormat} for more information on how the * substitution is performed. If a translation message does not exist * for the specified key, an error is logged and the key itself (plus * the arguments) is returned so that the caller need not worry about * handling a null response. */ public function get (key :String, ... args) :String { // if this string is tainted, we don't translate it, instead we // simply remove the taint character and return it to the caller if (key.charAt(0) === TAINT_CHAR) { return key.substring(1); } args = Util.unfuckVarargs(args); // if this is a qualified key, we need to pass the buck to the // appropriate message bundle if (key.indexOf(QUAL_PREFIX) == 0) { var qbundle :MessageBundle = _msgmgr.getBundle(getBundle(key)); return qbundle.get(getUnqualifiedKey(key), args); } // look up our message string, selecting the proper plurality // string if our first argument is an Integer var msg :String = getResourceString(key + getSuffix(args), false); // if the base key is not found, look to see if we should try to // convert our first argument to an Integer and try again if (msg == null) { if (getResourceString(key + ".n", false) != null) { // try converting the first arg to an int try { args[0] = StringUtil.parseInteger(args[0]); msg = getResourceString(key + getSuffix(args), false); } catch (err :Error) { // fall through... } } // if the msg is still null, we have a problem if (msg == null) { Log.getLog(this).warning("Missing translation message " + "[bundle=" + _path + ", key=" + key + "]."); // return something bogus return (key + args); } } return StringUtil.substitute(msg, args); } /** * A helper function for {@link #get(String,Object[])} that allows us * to automatically perform plurality processing if our first argument * is an {@link Integer}. */ protected function getSuffix (args :Array) :String { if (args.length > 0 && args[0] is int) { switch (args[0]) { case 0: return ".0"; case 1: return ".1"; default: return ".n"; } } return ""; } /** * Obtains the translation for the specified compound message key. A * compound key contains the message key followed by a tab separated * list of message arguments which will be subsituted into the * translation string. * *
See {@link MessageFormat} for more information on how the * substitution is performed. If a translation message does not exist * for the specified key, an error is logged and the key itself (plus * the arguments) is returned so that the caller need not worry about * handling a null response. */ public function xlate (compoundKey :String) :String { // if this is a qualified key, we need to pass the buck to the // appropriate message bundle; we have to do it here because we // want the compound arguments of this key to be translated in the // context of the containing message bundle qualification if (compoundKey.indexOf(QUAL_PREFIX) == 0) { var qbundle :MessageBundle = _msgmgr.getBundle( getBundle(compoundKey)); return qbundle.xlate(getUnqualifiedKey(compoundKey)); } // to be more efficient about creating unnecessary objects, we // do some checking before splitting var tidx :int = compoundKey.indexOf("|"); if (tidx == -1) { return get(compoundKey); } else { var key :String = compoundKey.substring(0, tidx); var argstr :String = compoundKey.substring(tidx+1); var args :Array = argstr.split("|"); // unescape and translate the arguments for (var ii :int = 0; ii < args.length; ii++) { // if the argument is tainted, do no further translation // (it might contain |s or other fun stuff) if (args[ii].indexOf(TAINT_CHAR) == 0) { args[ii] = unescape(args[ii].substring(1)); } else { args[ii] = xlate(unescape(args[ii])); } } return get(key, args); } } /** * Call this to "taint" any string that has been entered by an entity * outside the application so that the translation code knows not to * attempt to translate this string when doing recursive translations * (see {@link #xlate}). */ public static function taint (text :Object) :String { return TAINT_CHAR + text; } /** * Composes a message key with an array of arguments. The message can * subsequently be translated in a single call using {@link #xlate}. */ public static function compose (key :String, ... args) :String { args = Util.unfuckVarargs(args); var buf :StringBuilder = new StringBuilder(); buf.append(key, "|"); for (var ii :int = 0; ii < args.length; ii++) { if (ii > 0) { buf.append("|"); } var arg :String = String(args[ii]); for (var p :int = 0; p < arg.length; p++) { var ch :String = arg.charAt(p); if (ch == "|") { buf.append("\\!"); } else if (ch == "\\") { buf.append("\\\\"); } else { buf.append(ch); } } } return buf.toString(); } /** * A convenience method for calling {@link #compose(String,Object[])} * with a single argument that will be automatically tainted (see * {@link #taint}). */ public static function tcompose (key :String, ... args) :String { args = Util.unfuckVarargs(args); for (var ii :int = 0; ii < args.length; ii++) { args[ii] = taint(args[ii]); } return compose(key, args); } /** * Returns a fully qualified message key which, when translated by * some other bundle, will know to resolve and utilize the supplied * bundle to translate this particular key. */ public static function qualify (bundle :String, key :String) :String { if (bundle.indexOf(QUAL_PREFIX) != -1 || bundle.indexOf(QUAL_SEP) != -1) { throw new Error("Message bundle may not contain " + QUAL_PREFIX + " or " + QUAL_SEP); } return QUAL_PREFIX + bundle + QUAL_SEP + key; } /** * Returns the bundle name from a fully qualified message key. * * @see #qualify */ public static function getBundle (qualifiedKey :String) :String { if (qualifiedKey.indexOf(QUAL_PREFIX) != 0) { throw new Error(qualifiedKey + " is not a fully qualified message key."); } var qsidx :int = qualifiedKey.indexOf(QUAL_SEP); if (qsidx == -1) { throw new Error(qualifiedKey + " is not a valid fully qualified key."); } return qualifiedKey.substring(QUAL_PREFIX.length, qsidx); } /** * Returns the unqualified portion of the key from a fully qualified * message key. * * @see #qualify */ public static function getUnqualifiedKey (qualifiedKey :String) :String { if (qualifiedKey.indexOf(QUAL_PREFIX) != 0) { throw new Error(qualifiedKey + " is not a fully qualified message key."); } var qsidx :int = qualifiedKey.indexOf(QUAL_SEP); if (qsidx == -1) { throw new Error(qualifiedKey + " is not a fully qualified message key."); } return qualifiedKey.substring(qsidx + 1); } /** * Unescapes characters that are escaped in a call to compose. */ public static function unescape (val :String) :String { var bsidx :int = val.indexOf("\\"); if (bsidx == -1) { return val; } var buf :StringBuilder = new StringBuilder(); for (var ii :int = 0; ii < val.length; ii++) { var ch :String = val.charAt(ii); if (ch != "\\" || ii == val.length-1) { buf.append(ch); } else { // look at the next character ch = val.charAt(++ii); buf.append((ch == "!") ? "|" : ch); } } return buf.toString(); } /** The message manager via whom we'll resolve fully qualified * translation strings. */ protected var _msgmgr :MessageManager; /** The path that identifies the resource bundle we are using to * obtain our messages. */ protected var _path :String; /** The resource bundle from which we obtain our messages. */ protected var _bundle :IResourceBundle; /** Our parent bundle if we're not the global bundle. */ protected var _parent :MessageBundle; protected static const TAINT_CHAR :String = "~"; protected static const QUAL_PREFIX :String = "%"; protected static const QUAL_SEP :String = ":"; } }