---
description: >-
  https://betterprogramming.pub/how-to-do-javascript-localization-with-jquery-i18n-1320ff5d7a4e
---

# \[MultiLang] Localizing JavaScript apps with jQuery.i18n (ok) (full)

## Basic Usage <a href="#ba45" id="ba45"></a>

### Locale <a href="#id-639c" id="id-639c"></a>

```
$.i18n( {
    locale: 'en' // Locale is English
} );
```

### Loading <a href="#id-0cb3" id="id-0cb3"></a>

```
$.i18n().load( {
	en: {
		'message-hello': 'Hello World',
		'message-goodbye': 'Good bye'	},
	ja: 'i18n/messages-ja.json', // Messages for Japanese
	zh: 'i18n/messages-zh.json' // Messages for Chinese
} );
```

### Data API <a href="#id-854d" id="id-854d"></a>

```
$.i18n( 'message-hello' );
```

### Placeholders <a href="#id-24ab" id="id-24ab"></a>

```
var message = "Welcome to Medium, $1";
$.i18n(message, 'Wai Foong'); // "Welcome to Medium, Wai Foong"
```

### Plurals <a href="#id-25ff" id="id-25ff"></a>

```
var message = 'Box has {{PLURAL:$1|one egg|$1 eggs|12=a dozen eggs}}.';
$.i18n(message, 1); // "Box has one egg."
$.i18n(message, 6); // "Box has 6 eggs."
$.i18n(message, 12 ); // "Box has a dozen eggs."
```

### Gender <a href="#caf4" id="caf4"></a>

```
var message = "$1 edited {{GENDER:$2|his|her}} article";
$.i18n(message, 'Amy', 'female' ); "Amy edited her article"
$.i18n(message, 'Bob', 'male' ); "Bob edited his article"
```

![](https://2726517656-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M1E4Gk2ppVKb4olmnun%2F-MZdFAXNdBRdkRSfBmZZ%2F-MZdUtiosgqRo6T2TPw8%2FScreenshot_1.jpg?alt=media\&token=5d09c3bc-b219-436d-a862-12e3b4ad445c)

C:\xampp\htdocs\windows\jqueryi18n\demo.html

```
<!DOCTYPE>
<html lang="en" dir="ltr">
<head>
  <meta charset="utf-8">
  <title>Demo Application</title>
  <script src="js/jquery.js"></script>
  <script src="js/lib/CLDRPluralRuleParser/CLDRPluralRuleParser.js"></script>
  <script src="js/lib/jquery.i18n/jquery.i18n.js"></script>
  <script src="js/lib/jquery.i18n/jquery.i18n.messagestore.js"></script>
  <script src="js/lib/jquery.i18n/jquery.i18n.fallbacks.js"></script>
  <script src="js/lib/jquery.i18n/jquery.i18n.language.js"></script>
  <script src="js/lib/jquery.i18n/jquery.i18n.parser.js"></script>
  <script src="js/lib/jquery.i18n/jquery.i18n.emitter.js"></script>
  <script src="js/lib/jquery.i18n/jquery.i18n.emitter.bidi.js"></script>
  <script src="js/lib/history/jquery.history.js"></script>
  <script src="js/lib/url/url.min.js"></script>
  <script src="js/global.js"></script>
</head>
<body>
<ul class="switch-locale">
  <li><a href="#" data-locale="en">English</a></li>
  <li><a href="#" data-locale="ru">Русский</a></li>
</ul>
<h1 class="translate" data-args="app-title">Example Application</h1>
<h2 class="translate" data-args="welcome,John">Welcome</h2>
<p class="translate" data-args="letters,5"></p>
<div>
  <p><em class="translate" data-args="letter,Ann,female"></em></p>
  <p>letter's text...</p>
</div>
<div>
  <p><em class="translate" data-args="letter,Rick,male"></em></p>
  <p>letter's text...</p>
</div>
<p class="translate" data-args="about"></p>
<footer class="translate" data-args="copyright"></footer>
</body>
</html>
```

{% file src="https://2726517656-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M1E4Gk2ppVKb4olmnun%2F-MZdFAXNdBRdkRSfBmZZ%2F-MZdVGs9DKtAufH4QK7o%2Fjqueryi18n.zip?alt=media&token=aac889f7-4838-44a0-a222-678609f0b553" %}

## How To Do JavaScript Localization With jQuery.i18n <a href="#f85a" id="f85a"></a>

### A jQuery-based JavaScript internationalization library <a href="#id-6b15" id="id-6b15"></a>

[![Ng Wai Foong](https://miro.medium.com/fit/c/96/96/1*hkVmAWuyEtjb72BFw8w7vg.jpeg)](https://medium.com/@ngwaifoong92?source=post_page-----1320ff5d7a4e--------------------------------)[Ng Wai Foong](https://medium.com/@ngwaifoong92?source=post_page-----1320ff5d7a4e--------------------------------)Follow[Oct 12, 2019](https://betterprogramming.pub/how-to-do-javascript-localization-with-jquery-i18n-1320ff5d7a4e?source=post_page-----1320ff5d7a4e--------------------------------) · 5 min read![](https://miro.medium.com/max/60/1*Xw--P2Ic08QyLAfW-Sa_Tw.jpeg?q=20)![](https://miro.medium.com/max/5760/1*Xw--P2Ic08QyLAfW-Sa_Tw.jpeg)Photo by [Kyle Glenn](https://unsplash.com/@kylejglenn?utm_source=unsplash\&utm_medium=referral\&utm_content=creditCopyText) on [Unsplash](https://unsplash.com/s/photos/international?utm_source=unsplash\&utm_medium=referral\&utm_content=creditCopyText)

This article talks about the necessary steps required to do localization for your website via a JavaScript framework called jQuery.i18n. According to their [GitHub page](https://github.com/wikimedia/jquery.i18n):

> jQuery.i18n is a jQuery-based JavaScript internationalization library. It helps you to internationalize your web applications easily.
>
> This is a project by Wikimedia foundation’s [Language Engineering team](https://www.mediawiki.org/wiki/Wikimedia_Language_engineering) and used in some of the Wikimedia Foundation projects like Universal Language Selector.
>
> 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.

Let’s have a look at the following [demo ](https://thottingal.in/projects/js/jquery.i18n/demo/)to find out more about how you can localize the content of your web application without reloading your page.

There are four sections in this article:

1. The setup
2. Message file format
3. Basic usage
4. Conclusion

## 1. The setup <a href="#id-77b0" id="id-77b0"></a>

Create a folder at the root directory of your web application. I will just name it `jquery.i18n`. Then, we are going to include the necessary JavaScript files. You can clone the git files or just save the required files one by one from the GitHub folder.

### Clone (method 1) <a href="#id-2999" id="id-2999"></a>

Open up your Git terminal, and run the following:

```
git clone https://github.com/wikimedia/jquery.i18n.git
```

### Zip download (method 2) <a href="#d8ee" id="d8ee"></a>

You can download it as a zip file via the official [GitHub ](https://github.com/wikimedia/jquery.i18n)page.

### i18n JavaScript files <a href="#id-9de0" id="id-9de0"></a>

Go to your `src` folder and copy all the following files to the `jquery.i18n` folder (except the `languages` folder):

1. jquery.i18n.emitter.bidi.js
2. jquery.i18n.emitter.js
3. jquery.i18n.fallbacks.js
4. jquery.i18n.js
5. jquery.i18n.language.js
6. jquery.i18n.messagestore.js
7. jquery.i18n.parser.js

### CLDRPluralRuleParser <a href="#id-10f6" id="id-10f6"></a>

Go to the libs/[CLDRPluralRuleParser](https://github.com/santhoshtr/CLDRPluralRuleParser/tree/8baf9aedc428924fe6ee508b3d952cb5564efb3a/src)/src folder, and copy the following file to your `jquery.i18n` folder:

1. CLDRPluralRuleParser.js

### jQuery <a href="#id-4e0b" id="id-4e0b"></a>

This library is based on jQuery, and the latest version is recommended. Visit the following [link](https://code.jquery.com/), and download the version you desire. I’ll be using the minified version 3.4.1.

### Languages files <a href="#id-7b4f" id="id-7b4f"></a>

Create a `languages` folder in the same directory. We’ll fill it with the required files later on.

You should have the following files in the `jquery.i18n` folder.![](https://miro.medium.com/max/54/1*pDGZoAF4W0KUTjPK_h6z7Q.png?q=20)![](https://miro.medium.com/max/308/1*pDGZoAF4W0KUTjPK_h6z7Q.png)

## 2. Message File Format <a href="#id-8935" id="id-8935"></a>

All the language files will be based on the JSON file format. It’s highly recommended that you use the language code when naming each language or locale file. For example:

* English: en.json
* Japanese: ja.json
* Chinese: zh.json

Let’s create a simple JSON file using the following template as the boilerplate:

The metadata tag is used to store data that are not messages that serve as references or read-me information. The official site recommends:

> 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.

The file needs to be a valid JSON. Avoid using single quotation marks when dealing with key-value pairs. You can check the following [repository ](https://github.com/wikimedia/mediawiki/tree/master/languages/i18n)for more examples of valid JSON files.

## 3. Basic Usage <a href="#ba45" id="ba45"></a>

Localization can be done easily using the custom JavaScript code or the data API defined via the HTML tag.

### The setup <a href="#id-48f0" id="id-48f0"></a>

You need to link the JavaScript files to the HTML page of your web application. The following is an example of how I added it to my project.

### Locale <a href="#id-639c" id="id-639c"></a>

First and foremost, you will need to define the locale as the displayed message will be based on this parameter. You can easily define it using the following code:

```
$.i18n( {
    locale: 'en' // Locale is English
} );
```

If there is no definition of locale, this framework will rely on the language attribute given for the HTML tag.

```
<html lang="en">
```

Let’s say none of these are specified. The final fallback is that it’ll use the locale specified by the browser. It’s possible to change the locale by calling the following function:

```
$.i18n().locale = 'ja'; //Switching locale to Japanese
```

### Loading <a href="#id-0cb3" id="id-0cb3"></a>

There are quite a number of ways to load the JSON-formatted language files. They can be loaded by parts, but the easiest way is by the external URL as follows:

```
$.i18n().load( {
	en: {
		'message-hello': 'Hello World',
		'message-goodbye': 'Good bye'	},
	ja: 'i18n/messages-ja.json', // Messages for Japanese
	zh: 'i18n/messages-zh.json' // Messages for Chinese
} );
```

Remember to edit the language file and add `message-hello` and `message-goodbye` to it.

### Data API <a href="#id-854d" id="id-854d"></a>

The basic code to display the message is as follow:

```
$.i18n( 'message-hello' );
```

For displaying it without JavaScript code, you need to add a data-i18n attribute with value as the message key.

```
<li data-i18n="message-hello"></li>
```

You can specify the fallback text in case `message-hello` is not present as a key in the JSON files you’ve loaded.

```
<li data-i18n="message-hello">Fallback text here!</li>
```

### Placeholders <a href="#id-24ab" id="id-24ab"></a>

Messages are capable of taking placeholders, which are represented using the dollar sign (e.g., $1, $2, $3, etc.). They’ll be replaced during run time.

```
var message = "Welcome to Medium, $1";
$.i18n(message, 'Wai Foong'); // "Welcome to Medium, Wai Foong"
```

You can specify more than one placeholder by passing in more parameters in the function.

```
var message = "Welcome to $1, $2";
$.i18n(message, 'Medium', 'Wai Foong'); // "Welcome to Medium, Wai Foong"
```

### Plurals <a href="#id-25ff" id="id-25ff"></a>

This framework supports plural forms in the message via the following syntax: `{{PLURAL:$1|pluralform1|pluralform2|...}}`

Please note that `PLURAL` is not case sensitive. All the plural forms can be given in the above syntax, separated by a pipe sign.

The rules for each language are defined in the `CLDRPluralRuleParser.js` file. The following is an example of how you can display different messages based on the count of items:

```
var message = 'Box has {{PLURAL:$1|one egg|$1 eggs|12=a dozen eggs}}.';
$.i18n(message, 1); // "Box has one egg."
$.i18n(message, 6); // "Box has 6 eggs."
$.i18n(message, 12 ); // "Box has a dozen eggs."
```

### Gender <a href="#caf4" id="caf4"></a>

The gender forms are similar to plural forms and can be used to display a message based on the gender of the context:

```
var message = "$1 edited {{GENDER:$2|his|her}} article";
$.i18n(message, 'Amy', 'female' ); "Amy edited her article"
$.i18n(message, 'Bob', 'male' ); "Bob edited his article"
```

## 4. Conclusion <a href="#fd09" id="fd09"></a>

Let’s recap what we’ve learned today. We started with some basic introduction to this framework followed by some simple steps to set up and create the necessary files and folders.

Next, we moved on to learn the message format required when creating each language file. It must be a valid JSON-formatted file, and it’s highly recommended to name it based on the language code.

Finally, we learned the syntax, basic usage, and the proper ways to utilize this framework. It covers quite a lot of functionalities that are quite useful for localization.

Thanks for reading, and I hope to see you again in the next article. Have a great day!

## References <a href="#adb3" id="adb3"></a>

1. [https://github.com/wikimedia/jquery.i18n](https://github.com/wikimedia/jquery.i18n)
2. [https://phrase.com/blog/posts/step-step-guide-javascript-localization/](https://phrase.com/blog/posts/step-step-guide-javascript-localization/)
3. [https://thottingal.in/projects/js/jquery.i18n/demo/](https://thottingal.in/projects/js/jquery.i18n/demo/)
4. [https://github.com/wikimedia/mediawiki/tree/master/languages/i18n](https://github.com/wikimedia/mediawiki/tree/master/languages/i18n)
