resources/lib/jquery.i18n/README.md

   1 jQuery.i18n
   2 ===========
   3
   4 jQuery.i18n is a jQuery based Javascript internationalization library. It helps you to internationalize your web applications easily.
   5
   6 This is a project by Wikimedia foundation's [Language Engineering team](http://wikimediafoundation.org/wiki/Language_Engineering_team) and used in some of the Wikimedia Foundation projects like Universal Language Selector.
   7
   8 The jquery.i18n library uses a json based localization file format, "banana", which is used as the localization file format for  MediaWiki and other projects.
   9
  10 Features
  11 ========
  12 * Simple file format - JSON. Easily readable for humans and machines.
  13 * Author and metadata information is not lost anywhere. There are other file formats using comments to store this.
  14 * Uses MediaWiki convention for placeholders. Easily readable and proven convention. Example: ```There are $1 cars```
  15 * Supports plural conversion without using extra messages for all plural forms. Plural rule handling is done using CLDR. Covers a wide range of languages
  16 * Supports gender. By passing the gender value, you get correct sentences according to gender.
  17 * Supports grammar forms. jquery.i18n has a basic but extensible grammar conversion support
  18 * Fallback chains for all languages.
  19 * Data api- the message key. Example: ```<li data-i18n="message-key"></li>```.
  20 * Dynamic change of interface language without refreshing a webpage.
  21 * Nestable grammar, plural, gender support. These constructs can be nested to any arbitrary level for supporting sophisticated message localization
  22 * Message documentation through special language code ```qqq```
  23 * Extensible message parser to add or customize magic words in the messages. Example: ```{sitename}``` or ```[[link]]``
  24
  25
  26 Quick start
  27 -----------
  28
  29 ```bash
  30 git clone https://github.com/wikimedia/jquery.i18n.git
  31 cd jquery.i18n
  32 git submodule update --init
  33 ```
  34
  35 Testing
  36 -------
  37
  38 ```shell
  39 npm install
  40 ```
  41
  42 To run tests locally, run `npm test`, and this will run the tests.
  43
  44 Message File Format
  45 ===================
  46
  47 The message files are json formatted. As a convention you can have a folder named i18n inside your source code. For each language or locale, have a file named like languagecode.json.
  48
  49 Example:
  50 ```
  51 App
  52         |--src
  53         |--doc
  54         |--i18n
  55                 |--ar.json
  56                 |--de.json
  57                 |--en.json
  58                 |--he.json
  59                 |--hi.json
  60                 |--fr.json
  61                 |--qqq.json
  62 ```
  63
  64 A simple en.json file example is given below
  65
  66 ```json
  67 {
  68         "@metadata": {
  69                 "authors": [
  70                         "Alice",
  71                         "David",
  72                         "Santhosh"
  73                 ],
  74                 "last-updated": "2012-09-21",
  75                 "locale": "en",
  76                 "message-documentation": "qqq",
  77                 "AnotherMetadata": "AnotherMedatadataValue"
  78         },
  79         "appname-title": "Example Application",
  80         "appname-sub-title": "An example application with jquery.i18n",
  81         "appname-header-introduction": "Introduction",
  82         "appname-about": "About this application",
  83         "appname-footer": "Footer text"
  84 }
  85 ```
  86
  87 The json file should be a valid json. The ```@metadata``` holds all kind of data that are not messages. You can store author information, copyright, updated date or anything there.
  88
  89 Messages are key value pairs. It is a good convention to prefix your appname to message keys to make the messages unique. It acts as the namespace for the message keys. It is also a good convention to have the message keys with ```-``` separated words, all in lower case.
  90
  91 If you are curious to see some real jquery.i18n message file from other projects:
  92
  93 - message files of MediaWiki https://github.com/wikimedia/mediawiki-core/tree/master/languages/i18n
  94 - message files from jquery.uls project https://github.com/wikimedia/jquery.uls/blob/master/i18n
  95
  96 Single message file for all languages
  97 -------------------------------------
  98 There are some alternate message file format supported for different use cases. If your application is not big, and want all the translation in a single file, you can have it as shown in the below example:
  99
 100 ```json
 101 {
 102         "@metadata": {
 103                 "authors": [
 104                         "Alice",
 105                         "David",
 106                         "Santhosh"
 107                 ],
 108                 "last-updated": "2012-09-21",
 109                 "locale": "en",
 110                 "message-documentation": "qqq",
 111                 "AnotherMetadata": "AnotherMedatadataValue"
 112         },
 113         "en": {
 114                 "appname-title": "Example Application",
 115                 "appname-sub-title": "An example application with jquery.i18n",
 116                 "appname-header-introduction": "Introduction",
 117                 "appname-about": "About this application",
 118                 "appname-footer": "Footer text"
 119                 },
 120         "ml": {
 121                 "appname-title": "അപ്ലിക്കേഷന്‍ ഉദാഹരണം",
 122                 "appname-sub-title": "jquery.i18n ഉപയോഗിച്ചുള്ള അപ്ലിക്കേഷന്‍ ഉദാഹരണം",
 123                 "appname-header-introduction": "ആമുഖം",
 124                 "appname-about": "ഈ അപ്ലിക്കേഷനെപ്പറ്റി",
 125                 "appname-footer": "അടിക്കുറിപ്പു്"
 126         }
 127 }
 128 ```
 129
 130 Here the json file contains language code as key value and messagekey-message pairs as the value for all language pairs. You can choose this format or per-language file formats depending on your use case. Per-language files are more convenient for collaboration, version controlling, scalability, etc.
 131
 132 In this approach, it is also possible to give a file name as the value of language code.
 133
 134 ```json
 135 {
 136         "@metadata": {
 137                 "authors": [
 138                         "Alice",
 139                         "David",
 140                         "Santhosh"
 141                 ],
 142                 "last-updated": "2012-09-21",
 143                 "locale": "en",
 144                 "message-documentation": "qqq",
 145                 "AnotherMetadata": "AnotherMedatadataValue"
 146         },
 147         "en": {
 148                 "appname-title": "Example Application",
 149                 "appname-sub-title": "An example application with jquery.i18n",
 150                 "appname-header-introduction": "Introduction",
 151                 "appname-about": "About this application",
 152                 "appname-footer": "Footer text"
 153                 },
 154         "ml": "path/to/ml.json"
 155 }
 156 ```
 157
 158 Translation
 159 ===========
 160 To translate the jquery.i18n application, depending on the expertise of the translator, there are multiple ways.
 161
 162 * Editing the json files directly - Suitable for translators with technical background. Also suitable if your application is small and you want to work with only a small number of languages
 163 * Providing a translation interface along with your application: Suitable for proprietary or private applications with significant amount of translators
 164 * Using open source translation platforms like translatewiki.net. The MediaWiki and jquery.uls from previous examples use translatewiki.net for crowdsourced message translation. Translatewiki.net can update your code repo in regular intervals with updated translations. Highly recommended if your application is opensource and want localized to as many as languages possible with maximum number of translators.
 165
 166 Usage
 167 =====
 168
 169 ## Switching locale
 170
 171 While initializing the `jquery.i18n`, the locale for the page can be given using the `locale` option. For example
 172
 173 ```javascript
 174 $.i18n( {
 175     locale: 'he' // Locale is Hebrew
 176 } );
 177 ```
 178
 179 In case locale option is not given, `jquery.i18n` plugin will use the language attribute given for the html tag. For example
 180
 181 ```html
 182 <html lang="he" dir="rtl">
 183 ```
 184
 185 In this case the locale will be he(Hebrew). If that `lang` attribute is also missing, it will try to use the locale specified by the browser.
 186
 187 It is possible to switch to another locale after plugin is initialized. See below example:
 188
 189 ```javascript
 190 $.i18n({
 191     locale: 'he' // Locale is Hebrew
 192 });
 193 $.i18n( 'message_hello' ); // This will give the Hebrew translation of message key `message_hello`.
 194 $.i18n().locale = 'ml'; // Now onwards locale is 'Malayalam'
 195 $.i18n( 'message_hello' ); // This will give the Malayalam translation of message key `message_hello`.
 196 ```
 197
 198 ## Message Loading
 199
 200 JSON formatted messages can be loaded to the plugin using multiple ways.
 201
 202 ### Dynamic loading using `load` method.
 203
 204 Following example shows loading messages for two locales- localex, and localey. Here localex and localey are just examples. They should be valid IS0 639 language codes(eg: en, ml, hi, fr, ta etc)
 205
 206 ```javascript
 207 $.i18n().load( {
 208         'localex' : {
 209                 'message-key1' : 'message1' // Message for localex.
 210         },
 211         'localey' : {
 212                 'message-key1' : 'message1'
 213         }
 214 } );
 215 ```
 216
 217 If we want to load the messages for a specific locale, it can be done like this:
 218
 219 ```javascript
 220 $.i18n().load({
 221     'message-hello': 'Hello World',
 222     'message-welcome': 'Welcome'
 223 }, 'en');
 224 ```
 225
 226 Note the second argument for the `load` method. It should be a valid language code.
 227
 228 It is also possible to refer messages from an external URL. See below example
 229
 230 ```javascript
 231 $.i18n().load( {
 232         en: {
 233                 message_hello: 'Hello World',
 234         message_welcome: 'Welcome'
 235         },
 236         hi: 'i18n/messages-hi.json', // Messages for Hindi
 237         de: 'i18n/messages-de.json'
 238 } );
 239 ```
 240
 241 Messages for a locale can be also loaded in parts. Example
 242
 243 ```javascript
 244 $.i18n().load( {
 245         en: {
 246                 message_hello: 'Hello World',
 247         message_welcome: 'Welcome'
 248         }
 249 } );
 250
 251 $.i18n().load( {
 252         // This does not remove the previous messages.
 253         en: {
 254                 'message_header' : 'Header',
 255                 'message_footer' : 'Footer',
 256                 // This will overwrite message_welcome message
 257                 'message_welcome' : 'Welcome back'
 258         }
 259 } );
 260 ```
 261
 262 Since it is desirable to render interface messages instantly and not after a delay of loading the message files from a server, make sure that the messages are present at client side before using jQuery.i18n.
 263
 264 The library should expose an API to load an object containing key-value pair of messages. Example: ```$.i18n.load(data)```. This will return a ```jQuery.Promise```.
 265
 266 jquery.i18n plugin
 267 =========================
 268
 269 The jQuery plugin defines ```$.i18n()``` and ```$.fn.i18n()```
 270
 271 ```javascript
 272 $.i18n( 'message-key-sample1' );
 273 $.i18n( 'message-key-sample1' );
 274 $.i18n( 'Found $1 {{plural:$1|result|results}}', 10 ); // Message key itself is message text
 275 $.i18n( 'Showing $1 out of $2 {{plural:$2|result|results}}', 5,100 );
 276 $.i18n(' User X updated {{gender|his|her}} profile', 'male' );
 277
 278 $( '#foo' ).i18n(); // to translate the element matching jquery selector based on data-i18n key
 279 ```
 280
 281 Data API
 282 --------
 283
 284 It is possible to display localized messages without any custom JavaScript. For the HTML tags, add an attribute data-i18n with value as the message key. Example:
 285 ```html
 286 <li data-i18n="message-key"></li>.
 287 ```
 288
 289 It is also possible to have the above li node with fallback text already in place.
 290 ```html
 291 <li data-i18n="message-key">Fallback text</li>
 292 ```
 293
 294 The framework will place the localized message corresponding to message-key as the text value of the node. Similar to $('selector').i18n( ... ).
 295 This will not work for dynamically created elements.
 296
 297 Note that if data-i18n contains html markup, that html will not be used as the element content, instead, the text version will be used. $.fn.i18n is always about replacing text of the element. If you want to change the html of the element, you may want to use: ```$(selector).html($.i18n(messagekey))```
 298
 299 Examples
 300 ========
 301
 302 See http://thottingal.in/projects/js/jquery.i18n/demo/
 303
 304 Message format
 305 ==============
 306
 307 ## Placeholders
 308
 309 Messages take parameters. They are represented by $1, $2, $3, … in the message texts, and replaced at run time. Typical parameter values are numbers (Example: "Delete 3 versions?"), or user names (Example: "Page last edited by $1"), page names, links, and so on, or sometimes other messages.
 310
 311 ```javascript
 312 var message = "Welcome, $1";
 313 $.i18n(message, 'Alice'); // This gives "Welcome, Alice"
 314 ```
 315
 316
 317 ## Plurals
 318
 319 To make the syntax of sentence correct, plural forms are required. jquery.i18n support plural forms in the message using the syntax `{{PLURAL:$1|pluralform1|pluralform2|...}}`
 320
 321 For example:
 322
 323 ```javascript
 324 var message = "Found $1 {{PLURAL:$1|result|results}}";
 325 $.i18n(message, 1); // This gives "Found 1 result"
 326 $.i18n(message, 4); // This gives "Found 4 results"
 327 ```
 328 Note that {{PLURAL:...}} is not case sensitive. It can be {{plural:...}} too.
 329
 330 In case of English, there are only 2 plural forms, but many languages use more than 2 plural forms. All the plural forms can be given in the above syntax, separated by pipe(|)
 331
 332 ## Gender
 333 Similar to plural, depending on gender of placeholders, mostly user names, the syntax changes dynamically. An example in English is "Alice changed her profile picture" and "Bob changed his profile picture". To support this {{GENDER...}} syntax can be used as show in example
 334
 335 ```javascript
 336 var message = "$1 changed {{GENDER:$2|his|her}} profile picture";
 337 $.i18n(message, 'Alice', 'female' ); // This gives "Alice changed her profile picture"
 338 $.i18n(message, 'Bob', 'male' ); // This gives "Bob changed his profile picture"
 339 ```
 340
 341 Note that {{GENDER:...}} is not case sensitive. It can be {{gender:...}} too.
 342
 343 ## Grammar
 344
 345
 346 ```javascript
 347 $.i18n( { locale: 'fi' } );
 348
 349 var message = "{{grammar:genitive|$1}}";
 350
 351 $.i18n(message, 'talo' ); // This gives "talon"
 352
 353 $.i18n().locale = 'hy'; // Switch to locale Armenian
 354 $.i18n(message, 'Մաունա'); // This gives "Մաունայի"
 355 ```
 356
 357 ## Directionality-safe isolation
 358
 359 To avoid BIDI corruption that looks like "(Foo_(Bar", which happens when a string is inserted into a context with the reverse directionality, you can use `{{bidi:…}}`. Directionality-neutral characters at the edge of the string can get wrongly interpreted by the BIDI algorithm. This would let you embed your substituted string into a new BIDI context, //e.g.//:
 360
 361    "`Shalom, {{bidi:$1}}, hi!`"
 362
 363 The embedded context's directionality is determined by looking at the argument for `$1`, and then explicitly inserted into the Unicode text, ensuring correct rendering (because then the bidi algorithm "knows" the argument text is a separate context).
 364
 365
 366 Fallback
 367 ========
 368
 369 The plugin takes an option 'fallback' with the default value 'en'. The library reuses the fallback data available in MediaWiki for calculating the language fallbacks. Fallbacks are used when a message key is not found in a locale. Example fallbacks: sa->hi->en or tt->tt-cyrl->ru.
 370
 371 See jquery.i18n.fallbacks.js in the source.
 372
 373 Magic word support
 374 ===================
 375 * For plural, gender and grammar support, MediaWiki template-like syntax - {{...}} will be used.
 376 * There will be a default implementation for all these in $.i18n.language['default']
 377 * The plural, gender and grammar methods in ```$.i18n.language[ 'default' ]``` can be overridden or extended in ```$.i18n.language['languageCode']```.
 378 * Language-specific rules about Gender and Grammar can be written in languages/langXYZ.js files
 379 * Plural forms will be dynamically calculated using the CLDR plural parser.
 380
 381 Extending the parser
 382 --------------------
 383 Following example illustrates extending the parser to support more magic words
 384
 385 ```javascript
 386 $.extend( $.i18n.parser.emitter, {
 387         // Handle SITENAME keywords
 388         sitename: function () {
 389                 return 'Wikipedia';
 390         },
 391         // Handle LINK keywords
 392         link: function ( nodes ) {
 393                 return '<a href="' + nodes[1] + '">' + nodes[0] + '</a>';
 394         }
 395 } );
 396 ```
 397
 398 This will parse the message
 399 ```javascript
 400 $.i18n( '{{link:{{SITENAME}}|http://en.wikipedia.org}}' );
 401 ```
 402
 403 to
 404
 405 ```html
 406 <a href="http://en.wikipedia.org">Wikipedia</a>
 407 ```
 408
 409 Message documentation
 410 =====================
 411
 412 The message keys and messages won't give a enough context about the message being translated to the translator. Whenever a developer adds a new message, it is a usual practice to document the message to a file named qqq.json
 413 with same message key.
 414
 415 Example qqq.json:
 416 ```json
 417 {
 418         "@metadata": {
 419                 "authors": [
 420                         "Developer Name"
 421                 ]
 422         },
 423         "appname-title": "Application name. Transliteration is recommended",
 424         "appname-sub-title": "Brief explanation of the application",
 425         "appname-header-introduction": "Text for the introduction header",
 426         "appname-about": "About this application text",
 427         "appname-footer": "Footer text"
 428 }
 429
 430 ```
 431
 432 In MediaWiki and its hundreds of extensions, message documentation is a strictly followed practice. There is a grunt task to check whether all messages are documented or not. See https://www.npmjs.org/package/grunt-banana-checker