What Every Developer Ought to Know About jQuery I18n

JavaScript’s excellent internationalization solution is called jQuery.i18n. Learn here all you need to know to translate your jQuery application!

The internationalization of web applications is an important yet complex task. Each region and country around the world have different expectations when it comes to how text, messages, numbers, and dates should appear. Each user of a particular application expects that all text and messages are displayed in a familiar format. Luckily, there are a bunch of solutions available for JavaScript that enable you to internationalize. Some of them provide only a couple of helper functions, whereas others are full-fledged libraries with dozens of features. One such solution is jQuery i18n that is used for localization of MediaWiki and many other international websites. In this article, we will learn lots of aspects of the jQuery i18n library that you may not have known and discuss some examples. Happy reading!

Features of jQuery i18n

  • Keeps code separate from i18n content. This feature keeps the code modular and allows developers to load the i18n functionalities they need.
  • Uses the JSON format.
  • It allows a change in a language without refreshing the web page.
  • Handles the plural form without using additional messages. Rule handling is done using the Unicode Consortium’s Common Locale Data Repository (CLDR).
  • Corrects sentences according to gender by passing the gender value.
  • Supports grammar forms.

Powered by Wikimedia

As already mentioned above, jQuery.i18n library is maintained by Wikimedia Foundation team. Wikimedia, in turn, is the company behind Wikipedia, Wikinews and others. What’s interesting, jQuery.I18n was initially created to be used in Wikimedia’s own projects, for example in Universal Language Selector that is currently available in Wikipedia, Wikibooks, Wikiquote and other websites. The Language team takes care of the library. They launched project Milkshake (a fancy name, eh?) in 2012 aiming to create general I18n tools in jQuery. Members of the team decided to make jQuery.I18n framework (yeah, they call it “framework”, not “library”) open source and now it has hundreds of users all over the world. As long as Wikimedia is a solid company, you can be sure that this library will be maintained for a long period.

jQuery i18n Directory

Now let’s talk about organizing your I18n files. Usually, an app powered by jQuery.i18n will have a folder i18n with a handful of .json files named after the language. This is a common practice met in many popular frameworks. JSON format is recognized by Phrase, so you may easily import your translation files, modify them and export back. An example directory is displayed in Figure 1. [FIGURE 1]

jQuery i18n Translation Files

Translation Files Format

All translations (or messages, as they are called in library’s terms) are stored inside simple JSON files, which can be edited even using simple Notepad. JSON is a data storage format and the abbreviation means “JavaScript object notation”. This is a simple key-value format that is very popular nowadays: for the past years it has nearly superseded XML. Initially it was derived from JavaScript, but all in all it is language independent. Here is a small example of how JSON looks: https://gist.github.com/bodrovis/60bd7b4ad6d5490349e555d9a4266804 JSON files are advantageous because:

  1. They allow an easy way for translators to access text to be translated. This is very useful if the JSON files need to be sent out for translation services.
  2. They prevent direct access into the database.

Storing Translations in a Single File

In a JSON file for internationalization, the key-message pairs contain the names and values for all language pairs. Every key is in lowercase letters with “-“ separating the words, and is associated with a value in the chosen language. The JSON file can include meta information. Meta information can be defined as “information about information”. In relation to translations, it usually contains authors’ names, date of the last modification and a locale’s name (if you store translations inside separate files). Any information that describes a translation file can be put under the @metadata key (note the @ symbol). For example: https://gist.github.com/bodrovis/6fe2a8469404f1bda3aea548aef982f1 A separate JSON file is often created for each language type; however, all of the translations can also be put into a single file. The advantage of separate JSON files is that the files are less complex. However, a single JSON file can be used for small apps with a few dozens of messages. An example JSON file with a single language and @metadata is provided below: https://gist.github.com/bodrovis/60dd557f347c851b3220075eac56f027 Next, here is an example JSON file with multiple languages and @metadata: https://gist.github.com/bodrovis/79af8de720ac81d6a4e9b489d0ddcc70 Basically, you only need to provide a locale’s name and then put translations inside. It is also a common practice to prefix the keys with the application’s name, for example myapp-mykey.

Storing Translations in Multiple Files

For larger applications having all translations reside in a single file is usually not the best idea. It is easy to get overwhelmed by all the keys and values. Also, having a single file with all content is not very convenient when working with a version control system like Git. Therefore, you may divide messages into separate JSON files named after the locale: en.json, ru.json, de.json etc. Usually these files are stored inside the i18n directory. Here, for example, you may see how Wikimedia itself stores messages for their project. On top of that, you may extract messages for one or multiple locales in a separate file and then simply provide a path to it: https://gist.github.com/bodrovis/67a5cea81ca2d0e48e705ac80eb70445 So, it is up to you to decide how translations will be stored!

Documenting Translations

Usually localizing an application (or anything else really) does not mean simply translating it. Translators may require some context, additional explanations to understand how to localize a phrase better. This is a common problem when translating video games or films: if a translator does not understand the background behind a character, he may incorrectly localize some joke and its point will be lost. Therefore, jQuery.i18n allows you to localize your translations easily inside a strangely named qqq.json file. Creating such file is a really great idea that may come in handy for the translators. Inside the file you simply list all the message keys and some relevant information. For example, you may explain in what tone should the message sound (more or less formal), what is the point of some joke or catch phrase etc. Here is a small example of a qqq.json file: https://gist.github.com/bodrovis/161d8bd039d2934cdec0879dff71888e

Loading Translation Files

Translations for jQuery.I18n can be loaded with a simple load() function like this: https://gist.github.com/bodrovis/8e30bbf15de4bfc7af4fdacc8bc13e1d However, how do you know when the files are actually loaded so that you can perform additional operations? Suppose, for example, you want to bind a click event to a link; when it happens the locale should be changed to another one. Of course, this can be done after the page is loaded using document ready event, but at this point translations, most likely, won’t be ready. What to do? Meet promises. Promises simply means that some operation will be carried out only after another process has finished its work with some result. This concept is pretty simple yet powerful and in many cases is preferred over callbacks. To add a promise, simply chain a done() method after the load(): https://gist.github.com/bodrovis/ca3cb333c66675d2224ab1444b138498 So, the anonymous function inside the done() method will only be run after the load() succeeds. You may also chain a fail() method after the done() to instruct what do if loading was unsuccessful: https://gist.github.com/bodrovis/c1c20117bace61e3cf98973eab7e57d8


Data API

One interesting feature jQuery.i18n has is the support for HTML5 data- attributes. With this feature you can start localizing your application in virtually 5 seconds. All you need to do is create a translation file, for example: https://gist.github.com/bodrovis/5b6b5a36b6ea0d8c6dc54e97336d6f19 Then add some HTML tag on the page with the data-i18n attribute. This attribute should have the value equal to the translation key you want to employ: https://gist.github.com/bodrovis/e1b7938f44964894fc021cd7e4bf9f85 Inside the tag you may put fallback text to display if the translation fails to load or some other error occurs. Lastly, apply the i18n() method to the body: https://gist.github.com/bodrovis/8767ca8ca5e5038e79cc6dd8e6df1636 This is it! The library will automatically search for all data-i18n attributes and replace the tag’s contents with the corresponding value.


There are several ways to translate a jQuery.i18n application:

  1. Editing the JSON files directly. This is suitable for small applications with a limited number of languages.
  2. Have a translation interface with the application. This option works for proprietary or private applications with many translators.

Magic Words

We, developers, all love magic, especially when it can be easily understood and used. jQuery.i18n enables us to cast some magic too by introducing “magic words”. Actually, these “magic words” behave like templates supporting, for example, gender and plural forms. Suppose you want to display a phrase “You have 1 new message”. But what about 2 or more messages? Of course, you may say simply “You have 2 new message(s)”, but that’s not very beautiful. Instead, let’s take advantage of jQuery.i18n’s “magic word” called plural: https://gist.github.com/bodrovis/1c582f92e9549a8a031c604060aaaa60 $1 is a placeholder that will be set with some integer in a moment. PLURAL:, in turn, is our “magic word”. It will automatically decide which word to display based on the value of $1. Out of the box, jQuery.i18n knows how to work with plural forms in many languages, including Russian, Finnish, Armenian and others. Now all you need to do is localize this message with a simple line of code: https://gist.github.com/bodrovis/4c58a3e8b966e660421d8bfea81cf4fe Here we take the message and assign the value of 2 to our $1 placeholder. Simple, isn’t it? Gender is also supported by the library, but you must explicitly say which gender you wish to use – unfortunately, jQuery.i18n cannot guess it by the user’s name, for example. Here is our sample message: https://gist.github.com/bodrovis/f29524dd760e265abbe5b31a9246c84d In this example we have not one, but two placeholders: the first will store the name and the second one will host the gender itself. Now localize the message: https://gist.github.com/bodrovis/2b3329ad9714bb1856a3e57b74abe4f3 Lastly, note that “magic words” are case insensitive, so you may say both GENDER: and gender:.

Parser is Extendable

Apart from working with the existing “magic words”, you may extend jQuery.I18n’s parser to introduce custom ones. Suppose, you are tired of writing a long application’s name everywhere and want to insert it with an APPNAME “magic word”. Well, this is really easy to do: https://gist.github.com/bodrovis/9c6447e8a678595f944e19bc992972d2 When a trick’s secret is revealed, it appears to be so simple, eh? Under the hoods the “magic words” are functions that return some content. In this case, for example, we return a string with the app’s name. What’s more, “magic words” may depend on each other. For instance, let’s create a link template: https://gist.github.com/bodrovis/cfe785cb3649ee7b7fd71d6fc6d89d23 nodes local variable is going to contain an array of all passed arguments that you may easily reference. Now let’s use this template to link to the site’s homepage while interpolating its name: https://gist.github.com/bodrovis/ff3dec134c1979bf898545baeae29c6b


What happens if some key cannot be found for a given locale? Well, this is bad indeed but jQuery.i18n takes care of such scenario as well with the help of fallbacks. Fallback simply explains which locale to employ if a key was not found in the currently set one. You can include jquery.fallback.js file from the library’s source code into your app. It already sets some sane default fallbacks. For example, if a key was not found inside the Ukrainian locale, the library will try to search inside Russian, as these languages are somewhat similar: https://gist.github.com/bodrovis/58b3e40ac72b329e5d3a099f0ac10b91 Of course, you may provide multiple elements inside the array constructing fallback chains: https://gist.github.com/bodrovis/14c293253837d32283dcf6de74ba08b0


jQuery.i18n.properties is a jQuery plugin for internationalization. Similar to Java, jQuery.i18n may use resource bundles (.properties files). Resource bundles are used to store locale-specific information such as text messages. They allow an easy way of accessing locale-specific information and adding locales easily by adding additional resource bundles. The .properties files contain locale-specific key-value pairs and interprets these files based upon language and country codes.

Using jQuery.i18n.properties

The jquery.i18n.properties.js plugin can be downloaded from https://github.com/jquery-i18n-properties/jquery-i18n-properties. The plug-in should be included in the <head> section of your HTML page: https://gist.github.com/bodrovis/8e0490d398758db41f0093b8182b7460

Features of jQuery.i18n.properties

  • Works like Java i18n. Uses resource bundles (‘.properties’ files) for translations. Uses ISO-639 for language codes and ISO-3166 for country codes.
  • If no language is specified, uses the default browser language. The default language in the resource bundles is always used first. The user-specified language will be loaded next.
  • The resource bundle strings allow placeholder substitution, and there is support for namespaces in the keys.

Language Control

To make your code more efficient with less 404 errors, a languages.json file should be used. It defines the languages and the properties files that can be used. This file should be placed into the same directory as the language properties files. An example of a languages.json file is as follows: https://gist.github.com/bodrovis/8b42f51b977b61ba29f92a2be2b2d31a

Example using jQuery.i18n.properties

To create an HTML page using jquery.i18n.properties.js, the first step is to create a directory with the desired folders for the JavaScript files and the properties files. For this example, we will use the directory in Figure 2. [FIGURE 2] Next, the HTML code will be created. The HTML contains a dropdown that allows the user to select a language. The messages below the dropdown are localized based upon the language chosen. https://gist.github.com/bodrovis/121203316388ef3af91997532180247c

Define .properties files

The jquery.i18n.properties.js plugin uses .properties files for the translate text. There are three properties files used in this example:

  1. Messages.properties
  2. Messages_fr.properties
  3. Messages_tr.properties

The text in each properties files is shown below: https://gist.github.com/bodrovis/1b623113c46cad48f5ca4c8ace06ce72

Loading localized strings from .properties

To load the messages from the properties files, save the jquery.i18n.properties.js file in the js folder. The code below is a simple example of how the properties files are loaded. https://gist.github.com/bodrovis/f9bbd6051f2ebc380c060d69a098f33b


Optional String or String[] If not specified, the default language reported by the browser will be used.Optional String

Phrase Can Make Your Life Easier

Working with translation files is hard, especially when the app is big and supports many languages. You might easily miss some translations for a specific language which will lead to user’s confusion. And so Phrase can make your life easier! Grab your 14-day trial. Phrase supports many different languages and frameworks, including JavaScript. It allows to easily import and export translations data. What’s cool, you can quickly understand which translation keys are missing because it’s easy to lose track when working with many languages in big applications. On top of that, you can collaborate with translators as it’s much better to have professionally done localization for your website.


So, in this article we have discussed some facts about jQuery.i18n library by Wikimedia Foundation. Hopefully, you found this article useful and interesting! If you are looking for a detailed tutorial explaining how to use this tool in your application, you may read our Advanced Guide to jQuery i18n. Also, jQuery.I18n’s homepage provides a very nice documentation, so I recommend browsing it as well. And lastly, you may read about a couple of other solutions for JavaScript to enable I18n support in our Step-by-Step Guide to JavaScript Localization. Have you already used jQuery.i18n in your projects? What solution do you prefer yourself? Share your experience in the comments!

Originally published on The Phrase Blog.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store