diff options
Diffstat (limited to 'library/jquery.i18n/README.markdown')
| -rw-r--r-- | library/jquery.i18n/README.markdown | 152 |
1 files changed, 152 insertions, 0 deletions
diff --git a/library/jquery.i18n/README.markdown b/library/jquery.i18n/README.markdown new file mode 100644 index 000000000..cbd6e4199 --- /dev/null +++ b/library/jquery.i18n/README.markdown @@ -0,0 +1,152 @@ + +About +----- + +_jQuery-i18n_ is a jQuery plugin for doing client-side translations in javascript. It is based heavily on [javascript i18n that almost doesn't suck](http://markos.gaivo.net/blog/?p=100) by Marko Samastur, and is licensed under the [MIT license](http://www.opensource.org/licenses/mit-license.php). + +Installation +------------ + +You'll need to download the [jQuery library](http://docs.jquery.com/Downloading_jQuery#Current_Release), and include it before _jquery.i18n.js_ in your HTML source. See the _examples_ folder for examples. + +Usage +----- + +Before you can do any translation you have to initialise the plugin with a 'dictionary' (basically a property list mapping keys to their translations). + +```javascript +var my_dictionary = { + 'some text': 'a translation', + 'some more text': 'another translation' +} +$.i18n.setDictionary(my_dictionary); +``` + +Once you've initialised it with a dictionary, you can translate strings using the $.i18n._() function, for example: + +```javascript +$('div#example').text($.i18n._('some text')); +``` + +or using $('selector')._t() function + +```javascript +$('div#example')._t('some text'); +``` + +Wildcards +--------- + +It's straightforward to pass dynamic data into your translations. First, add _%s_ in the translation for each variable you want to swap in : + +```javascript +var my_dictionary = { + "wildcard example" : "We have been passed two values : %s and %s." +} +$.i18n.setDictionary(my_dictionary); +``` + +Next, pass an array of values in as the second argument when you perform the translation : + +```javascript +$('div#example').text($.i18n._('wildcard example', [100, 200])); +``` + +or + +```javascript +$('div#example')._t('wildcard example', [100, 200]); +``` + +This will output _We have been passed two values : 100 and 200._ + +Because some languages will need to order arguments differently to english, you can also specify the order in which the variables appear : + +```javascript +var my_dictionary = { + "wildcard example" : "We have been passed two values : %2$s and %1$s." +} +$.i18n.setDictionary(my_dictionary); + +$('div#example').text($.i18n._('wildcard example', [100, 200])); +``` + +This will output: _We have been passed two values: 200 and 100._ + +Building From Scratch +--------------------- + +You can build the regular, un-minified version simply by running _ant_: + +```bash +$ ant +Buildfile: build.xml + +jquery.i18n: + [echo] Building ./jquery.i18n.js + [echo] ./jquery.i18n.js built. + +BUILD SUCCESSFUL +Total time: 0 seconds +``` + +Before you can build the minified version yourself, you'll need to download the [Google Closure Compiler](http://closure-compiler.googlecode.com/files/compiler-latest.zip) and put it in a folder called _build_: + +```bash +$ mkdir build +$ cd build +$ wget http://closure-compiler.googlecode.com/files/compiler-latest.zip +$ unzip compiler-latest.zip +``` + +Once you have the compiler, you can build the minified version by running _ant min_: + +```bash +$ ant min +Buildfile: build.xml + +jquery.i18n: + [echo] Building ./jquery.i18n.js + [echo] ./jquery.i18n.js built. + +min: + [echo] Building ./jquery.i18n.min.js + [apply] Applied java to 1 file and 0 directories. + [delete] Deleting: /Users/dave/Documents/Code/jquery/jquery-i18n/tmpmin + [echo] ./jquery.i18n.min.js built. + +BUILD SUCCESSFUL +Total time: 1 second +``` + +Bug Reports +----------- + +If you come across any problems, please [create a ticket](https://github.com/recurser/jquery-i18n/issues) and we'll try to get it fixed as soon as possible. + + +Contributing +------------ + +Once you've made your commits: + +1. [Fork](http://help.github.com/fork-a-repo/) jquery-i18n +2. Create a topic branch - `git checkout -b my_branch` +3. Push to your branch - `git push origin my_branch` +4. Create a [Pull Request](http://help.github.com/pull-requests/) from your branch +5. That's it! + + +Author +------ + +Dave Perrett :: mail@recursive-design.com :: [@recurser](http://twitter.com/recurser) + + +Copyright +--------- + +Copyright (c) 2010 Dave Perrett. See [License](https://github.com/recurser/jquery-i18n/blob/master/LICENSE) for details. + + + |