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

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

Basic Usage

Locale

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

Loading

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

$.i18n( 'message-hello' );

Placeholders

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

Plurals

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

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"

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>

How To Do JavaScript Localization With jQuery.i18n

A jQuery-based JavaScript internationalization library

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:

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

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)

Open up your Git terminal, and run the following:

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

Zip download (method 2)

You can download it as a zip file via the official GitHub page.

i18n JavaScript files

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

Go to the libs/CLDRPluralRuleParser/src folder, and copy the following file to your jquery.i18n folder:

  1. CLDRPluralRuleParser.js

jQuery

This library is based on jQuery, and the latest version is recommended. Visit the following link, and download the version you desire. I’ll be using the minified version 3.4.1.

Languages files

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

2. Message File Format

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 for more examples of valid JSON files.

3. Basic Usage

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

The setup

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

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

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

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

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

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

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

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

  1. https://github.com/wikimedia/jquery.i18n

  2. https://phrase.com/blog/posts/step-step-guide-javascript-localization/

  3. https://thottingal.in/projects/js/jquery.i18n/demo/

  4. https://github.com/wikimedia/mediawiki/tree/master/languages/i18n

Previous[MultiLang] MultiLang.js (ok)Next[MultiLang] jQuery i18n những điều nên biết (ok)

Last updated