resources/jquery/jquery.localize.js

   1 /**
   2  * Simple Placeholder-based Localization
   3  *
   4  * Call on a selection of HTML which contains <html:msg key="message-key" /> elements or elements
   5  * with title-msg="message-key", alt-msg="message-key" or placeholder-msg="message-key" attributes.
   6  * <html:msg /> elements will be replaced with localized text, *-msg attributes will be replaced
   7  * with attributes that do not have the "-msg" suffix and contain a localized message.
   8  *
   9  * Example:
  10  *     // Messages: { 'title': 'Awesome', 'desc': 'Cat doing backflip' 'search' contains 'Search' }
  11  *     var html = '\
  12  *         <p>\
  13  *             <html:msg key="title" />\
  14  *             <img src="something.jpg" title-msg="title" alt-msg="desc" />\
  15  *             <input type="text" placeholder-msg="search" />\
  16  *         </p>';
  17  *     $( 'body' ).append( $( html ).localize() );
  18  *
  19  * Appends something like this to the body...
  20  *     <p>
  21  *         Awesome
  22  *         <img src="something.jpg" title="Awesome" alt="Cat doing backflip" />
  23  *         <input type="text" placeholder="Search" />
  24  *     </p>
  25  *
  26  * Arguments can be passed into uses of a message using the params property of the options object
  27  * given to .localize(). Multiple messages can be given parameters, because the params property is
  28  * an object keyed by the message key to apply the parameters to, each containing an array of
  29  * parameters to use. The limitation is that you can not use different parameters to individual uses
  30  * of a message in the same selection being localized - they will all recieve the same parameters.
  31  *
  32  * Example:
  33  *     // Messages: { 'easy-as': 'Easy as $1 $2 $3.' }
  34  *     var html = '<p><html:msg key="easy-as" /></p>';
  35  *     $( 'body' ).append( $( html ).localize( { 'params': { 'easy-as': ['a', 'b', 'c'] } } ) );
  36  *
  37  * Appends something like this to the body...
  38  *     <p>Easy as a, b, c</p>
  39  *
  40  * Raw HTML content can be used, instead of it being escaped as text. To do this, just use the raw
  41  * attribute on a msg element.
  42  *
  43  * Example:
  44  *     // Messages: { 'hello': '<b><i>Hello</i> $1!</b>' }
  45  *     var html = '\
  46  *         <p>\
  47  *             <!-- escaped: --><html:msg key="hello" />\
  48  *             <!-- raw: --><html:msg key="hello" raw />\
  49  *         </p>';
  50  *     $( 'body' ).append( $( html ).localize( { 'params': { 'hello': ['world'] } } ) );
  51  *
  52  * Appends something like this to the body...
  53  *     <p>
  54  *         <!-- escaped: -->&lt;b&gt;&lt;i&gt;Hello&lt;/i&gt; world!&lt;/b&gt;
  55  *         <!-- raw: --><b><i>Hello</i> world!</b>
  56  *     </p>
  57  *
  58  * Message keys can also be remapped, allowing the same generic template to be used with a variety
  59  * of messages. This is important for improving re-usability of templates.
  60  *
  61  * Example:
  62  *     // Messages: { 'good-afternoon': 'Good afternoon' }
  63  *     var html = '<p><html:msg key="greeting" /></p>';
  64  *     $( 'body' ).append( $( html ).localize( { 'keys': { 'greeting': 'good-afternoon' } } ) );
  65  *
  66  * Appends something like this to the body...
  67  *     <p>Good afternoon</p>
  68  *
  69  * Message keys can also be prefixed globally, which is handy when writing extensions, where by
  70  * convention all messages are prefixed with the extension's name.
  71  *
  72  * Example:
  73  *     // Messages: { 'teleportation-warning': 'You may not get there all in one piece.' }
  74  *     var html = '<p><html:msg key="warning" /></p>';
  75  *     $( 'body' ).append( $( html ).localize( { 'prefix': 'teleportation-' } ) );
  76  *
  77  * Appends something like this to the body...
  78  *     <p>You may not get there all in one piece.</p>
  79  *
  80  */
  81 ( function ( $, mw ) {
  82
  83 /**
  84  * Gets a localized message, using parameters from options if present.
  85  *
  86  * @function
  87  * @param {String} key Message key to get localized message for
  88  * @returns {String} Localized message
  89  */
  90 function msg( options, key ) {
  91         var args = options.params[key] || [];
  92         // Format: mw.msg( key [, p1, p2, ...] )
  93         args.unshift( options.prefix + ( options.keys[key] || key ) );
  94         return mw.msg.apply( mw, args );
  95 }
  96
  97 /**
  98  * Localizes a DOM selection by replacing <html:msg /> elements with localized text and adding
  99  * localized title and alt attributes to elements with title-msg and alt-msg attributes
 100  * respectively.
 101  *
 102  * @method
 103  * @param {Object} options Map of options to be used while localizing
 104  * @param {String} options.prefix String to prepend to all message keys
 105  * @param {Object} options.keys Message key aliases, used for remapping keys to a template
 106  * @param {Object} options.params Lists of parameters to use with certain message keys
 107  * @returns {jQuery} This selection
 108  */
 109 $.fn.localize = function ( options ) {
 110         var $target = this,
 111                 attributes = ['title', 'alt', 'placeholder'];
 112
 113         // Extend options
 114         options = $.extend( {
 115                 prefix: '',
 116                 keys: {},
 117                 params: {}
 118         }, options );
 119
 120         // Elements
 121         // Ok, so here's the story on this selector. In IE 6/7, searching for 'msg' turns up the
 122         // 'html:msg', but searching for 'html:msg' doesn't. In later IE and other browsers, searching
 123         // for 'html:msg' turns up the 'html:msg', but searching for 'msg' doesn't. So searching for
 124         // both 'msg' and 'html:msg' seems to get the job done. This feels pretty icky, though.
 125         $target.find( 'msg,html\\:msg' ).each( function () {
 126                 var $el = $(this);
 127                 // Escape by default
 128                 if ( $el.attr( 'raw' ) ) {
 129                         $el.html( msg( options, $el.attr( 'key' ) ) );
 130                 } else {
 131                         $el.text( msg( options, $el.attr( 'key' ) ) );
 132                 }
 133                 // Remove wrapper
 134                 $el.replaceWith( $el.html() );
 135         } );
 136
 137         // Attributes
 138         // Note: there's no way to prevent escaping of values being injected into attributes, this is
 139         // on purpose, not a design flaw.
 140         $.each( attributes, function ( i, attr ) {
 141                 var msgAttr = attr + '-msg';
 142                 $target.find( '[' + msgAttr + ']' ).each( function () {
 143                         var $el = $(this);
 144                         $el.attr( attr, msg( options, $el.attr( msgAttr ) ) ).removeAttr( msgAttr );
 145                 } );
 146         } );
 147
 148         // HTML, Text for elements which cannot have children e.g. OPTION
 149         $target.find( '[data-msg-text]' ).each( function() {
 150                 var $el = $( this );
 151                 $el.text( msg( options, $el.attr( 'data-msg-text' ) ) );
 152         } );
 153
 154         $target.find( '[data-msg-html]' ).each( function() {
 155                 var $el = $( this );
 156                 $el.html( msg( options, $el.attr( 'data-msg-html' ) ) );
 157         } );
 158
 159         return $target;
 160 };
 161
 162 // Let IE know about the msg tag before it's used...
 163 document.createElement( 'msg' );
 164
 165 }( jQuery, mediaWiki ) );