Enabling the Locale Module [Localization and Translation]

The locale module, which provides language handling functionality and  user interface translation for Drupal, is not

enabled when you install Drupal. This is in accordance with Drupal’s philosophy of enabling functionality only when needed.

You can enable thelocale module on the Modules page.  If Drupal has been installed using  a language translation other than

English,  the locale module is enabled as part  of the installation process. The examples in this chapter assume the locale

module is enabled.

User Interface Translation

The interface for Drupal is made up of words, phrases, and  sentences that communicate with the user. In the following

sections, you’ll see how they can be changed. Our examples will focus on string replacement, with the understanding that

translation has its foundation in string replacement.

Strings

From  a programming perspective, a string is a series  of characters, such as the five-character string Hello. The translation of strings forms  the basis  of user interface translation in Drupal. When  Drupal

prepares a string for output, it checks if the string needs tobe translated, so that if the English  language is enabled, the word “Hello” is displayed, while if the French language is enabled, the word “Bonjour” is displayed. Let’s examine how that happens

Translating Strings  with t()

All strings that will be shown to the end  user in Drupal should be run  through the  t() function; this is Drupal’s translate

function, with the function name shortened to “t” for convenience because of its frequent use.

The locale-specific part  of the t() function looks like this:

function locale($string  = NULL,  $context = NULL,  $langcode  = NULL)  { global  $language;

$locale_t = &drupal_static(  FUNCTION    );

if (!isset($string)) {

// Return all cached  strings if  no string was specified return  $locale_t;}

$langcode  = isset($langcode) ?  $langcode  : $language->language;

// code  that   grabs  the  translations from cache  or  the  database  removed from the  example for

// brevity’s  sake

return  ($locale_t[$langcode][$context][$string] === TRUE  ?  $string :

$locale_t[$langcode][$context][$string]);}

In addition to translation, the t() function also handles insertion of values  into placeholders in strings. The values  are typically 

user-supplied input, which must be run  through a text transformation before being displayed.

t('Hello, my  name is %name.', array('%name' => 'John');

Hello, my  name is  John.

The placement of the text to be inserted is denoted by placeholders, and  the text to be inserted is in a keyed array.This text transformation process is critical to Drupal security (see Chapter 21 for more information). 

Figure  19-1 shows you how  t()handles translation; see Figure  21-1 to see how t() handles placeholders.

Figure 19-1. How t() does translation and placeholder insertion, assuming the current language is set to French

Replacing Built-In Strings  with Custom Strings

Translating the user interface is essentially replacing one string  with another. Let’s start small, choosing just a few strings to change. There are a couple of possible solutions to the translation problem. We’ll approach them from the simplest to the most complex.The first involves editing your settings file, and the second involves the locale module. Let’s start by doing a simple

string replacement in the breadcrumb trail and  move  on to replacing Blog  with Journal.

String Overrides in settings.php

Find your settings.php file (typically at sites/default/settings.php). You may need to make the file writable before making

changes, as Drupal tries its best to keep this file read-only. Scroll to the end of settings.php. We’ll add ‘home’ =>

‘Sweet Home’ to the list of values  to be translated after removing the leading hash signs (#).

/**

*   String  overrides:

*

*   To  override  specific  strings  on your site  with  or  without  enabling  locale

*   module,  add an entry  to  this  list.  This  functionality  allows  you to  change

*   a  small  number  of  your site's  default  English  language  interface  strings.

*

*   Remove  the  leading  hash  signs  to  enable.

*/

$conf['locale_custom_strings_en']  = array( 'forum'  => 'Discussion  board','@count  min'  => '@count  minutes',

‘home’  => ‘Sweet  Home’,);

If you visit your site, you’ll notice that in the breadcrumb trail, Home has been changed to Sweet Home, as shown in Figure  19-2.Now that you know how to do string overrides, let’s go ahead and  replace the word Blog with the word Journal:

$conf['locale_custom_strings_en']  = array( 'Blog'  => 'Journal',);

Figure 19-2. The string Home is replaced  with Sweet  Home in the breadcrumb trail.

Then  enable the blog module on the Modules page.  Go to Add content -> Blog entry, and  you should see a screen like the

one shown in Figure  19-3.

Figure 19-3. The string Blog  entry has not become  Journal  entry.

What’s wrong? Why was your custom string  replacement array ignored? It’s because the string Blog entry  is not the

same as the string Blog. You can’t just pick sub strings for replacement; you have to match the full string.

How do you find all the strings that contain the word Blog so that you can replace each  string  with its Journal  equivalent?

The locale module can help  with this.

Replacing Strings with the Locale Module

Instead of using string replacement by defining a list of custom string  replacements in settings.php, you can use the locale

module to find strings for replacement and  define what  the replacements will be. A language translation is a set of custom

string replacements for Drupal. When  Drupal prepares to display a string, it will run  the string through the t() function as outlined previously. If it finds a replacement in the current language translation, it will use the replacement; if not, it will simply  use

the originalstring. This process, which is what  the locale() function does,  is shown in a simplified form in Figure

19-4. The approach is to create a language with the language code  en-US  containing only the string(s) we want replaced.

Figure 19-4. If the locale module does not find  a replacement string in the current language translation,

it will fall back to using the original string.

Okay, let’s begin the process of changing any strings containing “blog” to strings containing “journal.” Because Drupal will fall

back to using  the original string if no translation is found, we need to provide only the strings we want  to change. We can put the strings into a custom language and  let Drupal fall back to original strings for any strings we don’t provide. First, let’s add

a custom language to hold our custom strings. The interface for doing that is shown in Figure  19-5. We’ll call it English-custom and  use en-US for the language code  and  path prefix. Navigate to Configuration -> Languages -> Add a Language.

Figure 19-5. Adding a custom language for targeted  string translation

Now, enable your new language, and  make it the default, as shown in Figure  19-6. Click “Save configuration,” uncheck

the Enabled check box next to English, and  click “Save configuration” again, as shown in Figure  19-7. With only one

language enabled, users will not be presented with the somewhat confusing “Language settings” choice shown in Figure

19-8 when editing their user accounts.

Figure 19-6. Enabling the new language and selecting it as the default

Figure 19-7. Disabling English so that  English-custom will be the only enabled language

Figure 19-8. The user interface on the “My account” page, where a user may select the preferred language for

e-mail sent by the site. (The interface appears only if multiple languages are enabled.)

Okay, you’ve got a single language translation called  English-custom enabled. It is currently empty, since  we haven’t added

any string replacements yet. So for every string, Drupal will go through the process shown in Figure  19-4, fail to find a

stringreplacement in English-custom, and  fall back to returning the original English  string from the English  language.

Let’s set up some string replacements. Navigate to Configuration -> Translate interface, which is shown in Figure  19-9.

Figure 19-9. The overview page of the “Translate interface” screen

Drupal uses just-in-time translation. When  a page is loaded, each  string is passed through the t() function and  on through the

locale() function where, if the string is not already present in the locales_source and  locales_target database tables, it is

added to those tables. So the values  in the “Built-in interface” column in Figure  19-9 show that 1,020 strings have passed

through t() and  are available for translation. Go ahead and  click around to some other pages in Drupal and  then return to this

one. You should see that the number of strings has increased as Drupal encounters more and  more parts of the interface that

will need translation. We’ll now use the locale module’s web interface to translate some strings. After clicking the Translate

tab, we are presented with a search interface that allows us to find strings for translation. Let’s search for all of those 1,020 or more strings that are available to us so far. The search interface is shown in Figure  19-10.

Figure 19-10. The search interface for showing translatable strings

Selecting our language (English-custom), searching for all strings, and  leaving  the search box blank will show us all translatable

strings. Each string  has an “edit” link next to it. After the list of strings, the search interface is shown again  at the bottom of the page.  Since the list of strings is quite long, let’s reduce it to only the strings that contain the word “Translate.” Type the

word Translate in the “String contains” field, and  click the Filter button. The result should be a list of strings that contain the word“Translate,” as shown in Figure  19-11. Let’s change the string Translate interface to Translate language interface

by clicking the “edit” link for that string.

Figure 19-11. A list of translatable strings containing the word “Translate” and their statuses

After you’ve edited the string, you are returned to the Translate tab (see figure 19-12). The page should have changed from

“Translate interface” to “Translate language interface”.

Figure 19-12. The string "Translate" is now replace by the string "Translate language."

Go ahead and  search for the string Translate again. You should see in the resulting list of strings that the strike through is

removed from the Languages column for this entry, indicating that the string has been translated, as shown in Figure  19-13.

Figure 19-13. The list of translatable strings after editing “Translate”

Note that the original string is shown, not the translation. If you return to the Overview  tab, you will see that English-custom now has one replacement string available. Now that you’ve learned how to change strings, we can get on to the business of changing all occurrences of “blog” to “journal.” After enabling the blog module and  visiting  the blog-related pages

(such as /node/add/blog and   blog/1), the translatable strings should be available for us to translate.

The search at Configuration -> Translate interface is case-sensitive, so one search for “blog” and  another for “Blog” will show

us all the occurrences and  let us change them to equivalent replacement strings using our preferred words “journal” and

“Journal.”

That change is all well and  good, but it’s bothersome that the URL for creating a new journal entry is still http://example.com/?q=node/add/blog; shouldn’t it be http:// example.com/?q=node/add/journal instead? Sure, it should. We can fix that

quickly  by enabling the path module and  adding an alias with node/add/blog as the existing system path and  node/add/

journal as the alias. Presto! All references to “blog” have disappeared, and  you can use the site without shuddering at

seeing the word “blog.”