Translations and drupal.js
There are four main families of tools in drupal.js:
- Theming functions.
- Translation functions.
- Utility functions.
- Support for Drupal behaviors.
Even if you don’t think you need the translation functions, I advise you to read this article. The tools covered here play a very important role in Drupal, even providing additional security to your code.
Our focus in this article will be on the translation functions. When we talk about translation tools, what exactly are we talking about?
As is the case with the theming system, the drupal.js translation system is designed to provide an API similar to the server-side PHP translation system.
In order to show how things work, we will not only look at the translation functions, but also at how the larger translation system is used.
Translation and languages
One of the Drupal’s more distinguished points is its well-integrated support for multiple languages. Drupal has been translated into dozens of languages, and installing and enabling a translation is a simple process. For these reasons, Drupal has gained an international audience.
In order to see how translations work, we are going to walk through the process of enabling the translation system on the server. We will then return to the drupal.js library to see how it uses the system.
Translation functions are the portions of code that developers use to make it possible for code to perform translations when appropriate. The translation system is the part of Drupal that does the actual translation. We will start with this second part, the translation system, and then go back to the translation functions.
English is the default language for Drupal. In fact, it is the only one installed by default. But since Drupal provides a complete language translation subsystem, and Drupal code is developed to support translation, enabling multi-language support is a straightforward process.
We will begin by installing a new language.
There are three steps that must be performed the first time you install a language:
- Multi-language support must be turned on.
- Translation files must be downloaded and installed.
- Drupal’s translation preferences must be configured.
We will briefly walk through this process.
Turning on translation support
By default, Drupal’s translation support is disabled. It is disabled for the practical reason that if it is not needed, the performance hit incurred by the translation subsystem should be avoided.
Turning it on is a matter of enabling a couple of modules. These modules are included in the Drupal core, so there’s no need to download anything. All you need to do is go to Administer | Site building | Modules, and then check the boxes next to the Locale and Content translation modules.
Once you’ve done that, click on the Save configuration button at the bottom of the screen. That should do it.
Getting and installing translations
Dozens of translations are available in the Translations repository on the official Drupal.org web site. To find and download a new language, go to http://drupal.org/project/Translations and download the desired language.
Once you have the translation archive, you can install it by uncompressing the file in the same directory where Drupal is installed. For example, if Drupal is installed in /var/www/drupal (a common location for it on Linux servers), you will want to uncompress the translation file in /var/www/drupal. The language files will automatically be placed in the correct location.
The next thing to do is to let Drupal know that you have a new language installed.
Once we have downloaded and unpacked the desired language(s), we need to configure Drupal’s language support to determine how to handle multiple languages.
There are two steps to this process:
- Add the new language.
- Configure the global language settings.
In the first step, we are going to let Drupal know about the new language.
Adding the language
We’ve already installed the language, but we also need to tell Drupal that we want it to go through the process of scanning the language files and compiling a translation database. This process is called adding a language.
To do this, we need to go to the Administer | Site configuration | Languages page and click on the Add language tab as seen in the following screenshot:
On this screen you will need to select the language from the Language name drop-down list. Unfortunately, this list is not limited to the languages you have already installed, so you will have to find the language in the list. Languages are indexed by their English name. Thus, you should look for German instead of Deutsch.
Once you’ve found the language, click Add language and sit back while Drupal parses all of the language files.
After the parsing is finished, we are ready to move on to the next step.
We have multiple languages supported, now. But we need to tell Drupal how it should determine what language we want to see when we visit a page.
To configure this, we can click on the Configure tab on the Administer | Site configuration | Languages page. There is only one set of options on this page: Language negotiation.
These settings let us configure how Drupal will determine which language to display. By default, None is checked. This means only the default language will be used.
Path prefix only determines which language to use based on a language identifier string present at the beginning of the URL. For example, my site is running at http://localhost:8888/drupal/. I have English set as the default language, and the Spanish translation is also installed.
Using these settings if I type in the previous URL, I will see the page in English (the default language). However, if I type in the URL http://localhost:8888/drupal/es/, the site will be displayed in Spanish. The es identifier is a prefix to the Drupal portion of the URL. So if I want to view a node using the Spanish translation, the URL would look like this: http://localhost:8888/drupal/es/node/1.
Path translation and language prefixes
The URLs mentioned make use of Drupal’s clean URLs. By using Apache’s mod_rewrite module, data that would normally appear in a query string can be embedded in the URL. If you do not have clean URLs turned on, then the previous URL would look something like this: http://localhost:8888/drupal?q=es/node/1. With the query string clearly isolated, it’s a little easier to see how es is treated as a prefix.
The Path prefix with language fallback option is similar to the previous option, except that it adds one more step.
If the path provides a language prefix, then that language is used (assuming the language has been installed and added). But if no prefix is found, Drupal then checks the language preferences that the web browser sends in its HTTP headers. These look something like this:
User-Agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.5; en-US;
rv:126.96.36.199) Gecko/2008070206 Firefox/3.0.1
This is a subset of the HTTP headers my browser sent when requesting a page from Drupal (and I viewed the headers using Firebug).
The highlighted line shows the language preferences. Spanish (es) is the first language, with US English (en-us) and generic English (en) set as my second and third choices.
With Path prefix with language fallback enabled, when I type in http://localhost:8888/drupal/, I will get the page in Spanish because Drupal will inspect the Accept-language header and determine that it is the best language to use.
If the Accept-language header isn’t available, or there is no language match, then Drupal will fall back to the site’s default language.
Finally, the last language negotiation type is Domain name only. In this case, the domain name portion of the URL is used to determine language. For example, http://es.example.com would resolve to the Spanish language, while http://en.example.com would resolve to English.
For multi-language development work, I find the Path prefix only choice to be the easiest to work with.
The translation feature is used to translate the strings that appear in Drupal code. This is done manually by a dedicated team of translators. Consequently, enabling translation will not affect the content you create. For example, if you write content in English, it will not be translated to Spanish for you. Only the interface (built-in menus, module descriptions, and so on) will be translated.