10 Things About jQuery i18n You May Not Have Known

jQuery.I18n by Wikimedia Foundation is a great internationalization library with many features. In this article we will cover its key aspects that you may not have known.

Internationalization of web applications is an important yet complex task. 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.

jQuery.i18n is one of such libraries: it provides both basic support for internationalization as well as many additional goodies: gender support, fallback chains, message documentation and more. Out of the box it supports many languages, so you may start working with it right away.

In this article we will learn about some aspects of the jQuery.i18n library that you may not have known and discuss some examples. Happy reading!

Facts about jQuery.i18n

1. Translations Are Simple JSON Files

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:

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 the PhraseApp service, so you may easily import your translation files, modify them and export back.

2. You Choose How to Store Translations

If your app is small and has only a few dozens of messages, they can be placed in a single JSON file easily:

Basically, you only need to provide a locale’s name and then put translations inside. It is a common practice to prefix the keys with the application’s name (appname in this example). Keys are usually written in lowercase, with individual words separated by hyphens.

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:

So, it is up to you to decide how translations will be stored!

3. Meta Information Can Be Added

Apart from storing the actual translations, you will probably want to attach some meta information to them. 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:

So, you are free to store any metadata along with your translations and it won’t be lost!

4. Translations Can Be Documented

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:

5. Supports 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:

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:

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:

This is it! The library will automatically search for all data-i18n attributes and replace the tag’s contents with the corresponding value.

6. Supports Promises

Translations for jQuery.I18n can be loaded with a simple load() function like this:

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():

So, the anonymous function inside the done() method will only be run after the load() suceeds. You may also chain a fail() method after the done() to instruct what do if loading was unsuccessful:

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

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

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:

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:

Lastly, note that “magic words” are case insensitive, so you may say both GENDER: and gender:.

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

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:

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:

9. Supports Fallbacks

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:

Of course, you may provide multiple elements inside the array constructing fallback chains:

10. Powered by Wikimedia

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.

PhraseApp Makes 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 PhraseApp can make your life easier!

Grab your 14-days trial. PhraseApp supports many different languages and frameworks, including JavaScript of course. 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!

I thank you for staying with me and happy coding.

Also published on Medium.