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 the PhraseApp service, so you may easily import your translation files, modify them and export back. An example directory is displayed in Figure 1.
jQuery i18n Translation Files
Translation Files Format
JSON files are advantageous because:
- 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.
- 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:
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:
Next, here is an example JSON file with multiple languages and
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
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:
So, it is up to you to decide how translations will be stored!
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:
Loading Translation Files
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
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:
|Switching locale||The locale for the web page can be set using the |
To switch to another locale after plugin is already initialized:
|Message Loading||Messages can be loaded for a specific locale or more than one locale: |
|Message Format – Placeholders||Placeholders are represented with the $1, $2, $3 variables in the messages. They are replaced during runtime.|
|Message Format – Plurals||In English, there are only two plural forms, but in many other languages, there are more than two plural forms.|
|Message Format – Gender||The syntax is: |
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
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:
- Editing the JSON files directly. This is suitable for small applications with a limited number of languages.
- Have a translation interface with the application. This option works for proprietary or private applications with many translators.
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
$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
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
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:
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:
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.
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:
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.
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:
Example using jQuery.i18n.properties
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.
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:
The text in each properties files is shown below:
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.
Optional String or String If not specified, the default language reported by the browser will be used.Optional String
|name||File name or portion of the file name that represents a resource bundle.|
|language||The ISO-639 Language code (‘en’, ‘fr’) and, optionally, ISO-3166 country code (‘en_US’, ‘pt_BR’).|
|path||Path to the directory that contains ‘.properties‘ files to load.||Optional String|
|cache||Bundles are cached by the browser or forcibly reloaded. The default is to forcibly re-load.||Optional boolean|
|encoding||Type of encoding for bundles. Property file resource bundles are specified in ISO-8859-1 format. Defaults to UTF-8 format.||Optional String|
|callback||A callback function is called when script execution is completed.||Optional function()|
PhraseApp 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 PhraseApp can make your life easier!
So, in this article we have discussed some facts about jQuery.i18n library by Wikimedia Foundation. Hopefully, you found this article useful and interesting!
Have you already used jQuery.i18n in your projects? What solution do you prefer yourself? Share your experience in the comments!