153 lines
4.0 KiB
Markdown
153 lines
4.0 KiB
Markdown
|
|
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.
|
|
|
|
|
|
|