Skip to content

Commit 6ebcd41

Browse files
jgollajgolla
committed
Updating README to copy over original read me
1 parent 97cd314 commit 6ebcd41

File tree

1 file changed

+155
-17
lines changed

1 file changed

+155
-17
lines changed

‎README.md

Lines changed: 155 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,170 @@
1-
# Localize
1+
# jquery.localize.js
22

33
[![Build Status](https://travis-ci.org/jgolla/jquery-localize.png?branch=master)](https://travis-ci.org/jgolla/jquery-localize)
44

55
A jQuery plugin that makes it easy to i18n your static web site.
66

7+
## Synopsis
8+
* Lazily loads JSON translation files based on a simple naming convention.
9+
* By default, applies the translations to your document based on simple attribute convention.
10+
* Tested with jQuery versions 1.7.2, 1.8.3, 1.9.1, 1.10.2, 1.11.0, 2.0.3, 2.1.0
11+
712
## Getting Started
813
Download the [production version][min] or the [development version][max].
914

1015
[min]: https://raw.github.com/jgolla/jquery-localize/master/dist/localize.min.js
1116
[max]: https://raw.github.com/jgolla/jquery-localize/master/dist/localize.js
1217

13-
In your web page:
18+
### Load the jquery-localize plugin on your page.
19+
20+
It's the file located at `build/jquery.localize.js`
21+
22+
### Mark up tags whose content you want to be translated
23+
24+
Somewhere in your html:
25+
26+
<h1 data-localize="greeting"> Hello! </h1>
27+
28+
### Provide a JSON language file that has translations:
29+
30+
example-fr.json:
31+
32+
{
33+
"greeting": "Bonjour!"
34+
}
35+
36+
### Use the localize plugin.
37+
38+
// In a browser where the language is set to French
39+
$("[data-localize]").localize("example")
40+
41+
// You can also override the language detection, and pass in a language code
42+
$("[data-localize]").localize("example", { language: "fr" })
43+
44+
## Gory Details
45+
46+
### Language file loading
47+
48+
The first argument of the localize method is the name of the language pack. You might have a different language pack for different parts of your website.
49+
50+
Here's an example of loading several language packs:
51+
52+
$("[data-localize]")
53+
.localize("header")
54+
.localize("sidebar")
55+
.localize("footer")
56+
57+
58+
If the language of the browser were set to "fr", then the plugin would try to load:
59+
60+
* header-fr.json
61+
* sidebar-fr.json
62+
* footer-fr.json
63+
64+
if the language of the browser also had a country code, like "fr-FR", then the plugin would ALSO try to load:
65+
66+
* header-fr-FR.json
67+
* sidebar-fr-FR.json
68+
* footer-fr-FR.json
69+
70+
This let's you define partial language refinements for different regions. For instance, you can have the base language translation file for a language that translates 100 different phrases, and for countries were maybe a some of those phrases would be out of place, you can just provide a country-specific file with _just those special phrases_ defined.
71+
72+
### Skipping Languages (aka Optimizing for My Language)
73+
74+
This is useful if you've got a default language. For example, if all of your content is served in english, then you probably don't want the overhead of loading up unecessary (and probably non-existant) english langauge packs (foo-en.json)
75+
76+
You can tell the localize plugin to always skip certain languages using the skipLanguage option:
77+
78+
# using a string will skip ONLY if the language code matches exactly
79+
# this would prevent loading only if the language was "en-US"
80+
$("[data-localize]").localize("example", { skipLanguage: "en-US" })
81+
82+
# using a regex will skip if the regex matches
83+
# this would prevent loading of any english language translations
84+
$("[data-localize]").localize("example", { skipLanguage: /^en/ })
85+
86+
# using an array of strings will skip if any of the strings matches exactly
87+
$("[data-localize]").localize("example", { skipLanguage: ["en", "en-US"] })
88+
89+
### Applying the language file
90+
91+
If you rely on the default callback and use the "data-localize" attribute then the changes will be applied for you.
92+
93+
### Examples:
94+
95+
**HTML:**
96+
97+
<p data-localize="title">Tracker Pro XT Deluxe</p>
98+
<p data-localize="search.placeholder">Search...</p>
99+
<p data-localize="search.button">Go!</p>
100+
<p data-localize="footer.disclaimer">Use at your own risk.</p>
101+
<p data-localize="menu.dashboard">Dashboard</p>
102+
<p data-localize="menu.list">Bug List</p>
103+
<p data-localize="menu.logout">Logout</p>
104+
105+
**application-es.json (fake spanish)**
106+
107+
{
108+
"title": "Tracker Pro XT Deluxo",
109+
"search": {
110+
"placeholder": "Searcho...",
111+
"button": "Vamos!"
112+
},
113+
"footer": {
114+
"disclaimer": "Bewaro."
115+
},
116+
"menu": {
117+
"dashboard": "Dashboardo",
118+
"list": "Bug Listo",
119+
"logout": "Exito"
120+
}
121+
}
122+
123+
**Localize it!**
124+
125+
$("[data-localize]").localize("application", { language: "es" })
126+
127+
### Callbacks
128+
129+
You can provide a callback if you want to augment or replace the default callback provided by the plugin. Your callback should take at least 1 argument: the language data (contents of your json file). It can optionally accept a second argument, which is a reference to the default callback function. This is handy if you still want the default behavior, but also need to do something else with the language data.
130+
131+
$("[data-localize]").localize("application", {
132+
language: "es",
133+
callback: function(data, defaultCallback){
134+
data.title = data.title + currentBugName();
135+
defaultCallback(data)
136+
}
137+
})
138+
139+
See the test/samples for working examples.
140+
141+
# Contributing
142+
143+
This plugin is written in [CoffeeScript](http://jashkenas.github.com/coffee-script/).
144+
The included `builder` script will run `coffee` with the necessary flags to
145+
automatically update the compiled javascript in the build/ directory any time you
146+
save changes to the coffee code under src/.
147+
148+
If you're interested in contributing, please fork the [repository](https://github.com/coderifous/jquery-localize),
149+
make your changes, and send pull-requests.
150+
151+
Tests use QUnit. Run them by serving from the root of the project and
152+
navigating to the test/ directory, which has an index.html that takes it from
153+
there.
154+
155+
Learn more about [how to fork](http://help.github.com/fork-a-repo/) and
156+
[pull-requests](http://help.github.com/pull-requests/).
157+
158+
# Credits & Licensing
159+
160+
Copyright (c) Jim Garvin (http://github.com/coderifous), 2008.
14161

15-
```html
16-
<script src="jquery.js"></script>
17-
<script src="dist/localize.min.js"></script>
18-
<script>
19-
jQuery(function($) {
20-
$.awesome(); // "awesome"
21-
});
22-
</script>
23-
```
162+
Dual licensed under the GPL (http://dev.jquery.com/browser/trunk/jquery/GPL-LICENSE.txt) and MIT (http://dev.jquery.com/browser/trunk/jquery/MIT-LICENSE.txt) licenses.
24163

25-
## Documentation
26-
_(Coming soon)_
164+
Written by Jim Garvin (@coderifous) for use on LMGTFY.com.
165+
Please use it, and contribute changes.
27166

28-
## Examples
29-
_(Coming soon)_
167+
http://github.com/coderifous/jquery-localize
30168

31-
## Release History
32-
_(Nothing yet)_
169+
Based off of Keith Wood's Localisation jQuery plugin.
170+
http://keith-wood.name/localisation.html

0 commit comments

Comments
 (0)