Exporting Your Translation [Localization and Translation]

After you’ve gone  through the work of selecting and  translating the strings you want  to change, it would be a shame to have

to do it all over again  when you set up your next Drupal site. By using the Export  tab at Configuration -> Translate interface,

you can save the translation to a special file called  a portable object (.po) file. This file will contain all of the strings that Drupal  has

passed through t(), as well as any replacement strings you have defined.

Portable Object Files

The first few lines of the file that results from exporting our English-custom translation follow:

#  English-Custom  translation of  Drupal 7

#  Generated  by admin <toddtomlinson@serverlogic.com>

#

msgid "" msgstr  ""

"Project-Id-Version: PROJECT  VERSION\n"

"POT-Creation-Date:  2010-08-08 06:01-0700\n" "PO-Revision-Date: 2010-08-08 06:01-0700\n"

"Last-Translator: NAME   <EMAIL@ADDRESS>\n" "Language-Team:  LANGUAGE  <EMAIL@ADDRESS>\n" "MIME-Version:  1.0\n"

"Content-Type:  text/plain; charset=utf-8\n" "Content-Transfer-Encoding: 8bit\n"

#:  misc/drupal.js

msgid "An   AJAX  HTTP  error  occurred." msgstr  ""

#:  misc/drupal.js

msgid "HTTP  Result   Code: !status" msgstr  ""…

The  .po  file  consists of some metadata headers followed by the translated strings. Each string  has three components: a comment thatshows where the string  first occurred, an msgid denoting the original string, and  an msgstr  denoting the translated string to use. For a

full description of the .po file format, see www.gnu.org/software/gettext/manual/gettext.html#PO-Files.

The en-US.po file can now be imported into another Drupal site (that has the locale module enabled) using  the import

tab at Configuration -> Translate interface.

Portable Object Templates

While a translation consists of some metadata and  a lot of original and  translated strings, a portable object template (.pot) file contains allthe strings available for translation, without any translated strings. This is useful  if you are starting a language translation fromscratch or want  to determine whether any new strings were added to Drupal since  the last version before modifying your site (another way to

find this out would be to upgrade a copy of your Drupal site and search for untranslated strings as shown in the “Replacing Built-In Strings  with Custom Strings” section).

Starting a New Translation

You can download the translation files for Drupal core as well as for many contributed modules in dozens of languages from http://

localize.drupal.org. On this section of Drupal.org, you will find language-specific translation files (.po files) that can be downloaded and

installed, immediately providing multilingual capabilities on your site. You may also wish to install the Localized Drupal (http://drupal.

org/project/l10_install) module, which program matically pulls user interface translations from http://localize.drupal.org, and  the

Localization Client module (http://drupal.org/ l10n_client), which provides easy ways to localize your site interface through an on-page localization editor interface—allowing customization of the interface translation right onthe web pages that are being viewed.

Generating .pot Files with Translation Template Extractor

The contributed translation template extractor module (see http://drupal.org/project/potx) can generate .pot files for you.

This is useful  if you’ve written your own module or downloaded a contributed module for which there is no existing translation.

The translation template extractor module contains both a command-line version and  a web-based version of the extractor.

If you are familiar with the xgettext program for Unix, think of this module as a Drupal-savvy version of that program. This

module is used under the hood at http:// localize.drupal.org to generate translation files.

Creating a .pot File for Your Module

Let’s generate a .pot file for the job post  module we created in Chapter 8. First, we’ll need to install the translation template extractor module. Copy the download link from http://drupal.org/project/potx,  and  install the module by navigating to Modules page and 

clicking the “Install new module” link. Paste  the download link inthe “Install from a URL” text box and  click the Install button.

Using the Command Line

Copy potx.inc  and  potx-cli.php  from the potx module’s directory into the job_post module’s directory at sites/all/modules

/custom/job_post. Next, we need to run the extractor, so it can create the.pot files.

Here are the results from running the extractor:

$  cd sites/all/modules/custom/job_post

$  php potx-cli.php

Processing  sponsor.tpl.php... Processing  job_post.module... Processing  job_post.install... Processing  job_post.info...

Let’s see what  was generated:

general.pot	job_post.install	potx.inc
installer.pot	job_post.module	sponsor.tpl.php
job_post.info	potx-cli.php

Running the extractor script resulted in a new file called  general.pot, which contains the strings from sponsor.tpl.php, job_post.module, job_post.info,  and  job_post.install. The script placed all the strings into general.pot by default, but it can generateseparate files

if you’d prefer. Run the following to see the various options offered by the extractor script.

$  php potx-cli.php  –-help

In the present case, it’s handy to have all of the strings in one file. If we were to share this translation template with others, we’d

create a  translations  subdirectory inside the annotate directory, move  the general.pot  into the translations directory, and rename it

annotate.pot. If we then made a French translation by opening the combined .pot  file, translating the strings, and  saving it as fr.po, our module directory would look like this:

general.pot	job_post.install	potx.inc
installer.pot	job_post.module	sponsor.tpl.php
job_post.info	potx-cli.php
translations/

annotate.pot

fr.po

Using the Web-Based Extractor

Instead of using  the command line, you can extract strings from your module using  the web-based user interface
provided by the translation template extractor module. After making sure  that you have installed the module, go to the Modules page,  and  enableboth the job_post and  translation template extractor modules. Next, go to Configuration -> Translate interface,
and  notice the new Extract  tab. Click it, and  you’ll be able to generate a .pot file by expanding the Directory “sites/all/
modules” group, and withinthat expanded list the module that you want  to generate the translation for. Next select  the
“Language independent template” radio button, and  click the Extract  button, as shown in Figure  19-14. The .pot file will be
downloaded via your web browser. You canthen place  the .pot file in the module’s directory as we did with the command-line extractor.

Creating .pot Files for an Entire  Site

If you wish to create .pot files for all translatable strings in your site, place  the  potx.inc and  potx- cli.php files at the rootof your site, ensure you have write access to that current directory, and  run potx-cli.php. You would run  the script from the
command line with the mode parameter set to core if you want  to generate .pot files with the same layout as those
available at http://drupal.org/ project/Translations:
$  php potx-cli.php  --mode=core

The script always outputs .pot files in the same directory the script is in; for example, modules- aggregator.pot will be
created in the root directory of your site, not in modules/aggregator/. The name of the.pot file reflects where it was found. So in theprevious example, a sites-all-modules-custom- annotate.pot file would be generated.

Installing a Language Translation

Drupal can be installed in a language other than English  or the language translation can be added later. Let’s cover both
possibilities.
Setting Up a Translation at Install  Time

Drupal’s installer recognizes installer translations with the st() function rather than t(), which isn’t available to the installer at
runtime because, well, Drupal isn’t installed yet. Installer translations are offered as a choice during installation and  are based onthe installer.pot file (see the “Getting .pot Files for Drupal” section).
To view the installer’s translation capabilities in action, let’s download the French translation of Drupal from www.drupal.org/project/translations. This results in the file fr-7.x-1.1.tar.gz. You can tell from the.  tar.gz ending that this is a .tar
file that has been compressed with GZIP compression. One way to extract the file is by using  the Unix tar utility:
$  tar  -xzvf fr-7.x-1.1.tar.gz

After successful extraction of the translation, additional folders called  translations should be found in your Drupal directories. For example, the profiles/default folder  (where Drupal’s default installation profile lives) now has a translations  sub folder containing a fr.po  file. That’s the French translation of the installer. When  Drupal’s installer runs, you can see the new
choice presented, as shown in Figure  19-15.
If you choose French, the installation will proceed in French, and  the default language for the site will be set to French.

Figure 19-15. When a .po file exists in the installation profile’s translations subdirectory,

Drupal’s installer allows you to choose a language for the installer.

Installing a Translation on an Existing Site

To install a language translation on an existing site, you can add  the language by navigating to Configuration -> Languages and
clicking the “Add language” tab. Next, simply  choose the language and click “Add language,” as shown in Figure  19-16.
The new language will then be shown in the table at Configuration -> Languages.

Figure 19-16. Installing a language

Right-to-Left Language Support

The directionality of a language is displayed in the list of language translations that have been added to Drupal, as shown in
Figure  19-17.

Figure 19-17. Right-to-left languages can be identified using the Direction column of the language table.

Drupal’s support for right-to-left languages such as Hebrew is at the theming layer. When  Drupal is informed that a style sheet
should be included in the current page,  and  the current language is a right- to-left language, Drupal will check for a corres ponding style sheet name that ends in -rtl.css. If that style sheet exists, it will be loaded in addition to the requested
style sheet. The logic is shown in Figure 19-18. Thus,  themes that support right-to-left languages generally have the styles
defined in the main style sheet,and  CSS overrides defined in the corresponding right-to-left style sheet.

For example, if the current language is Hebrew and  the theme is set to Seven, when Drupal adds the themes/seven/style.cssstyle sheet, the themes/seven/style-rtl.css file is included as well. Check out the right-to-left style sheets in Drupal’s
default themes to see what  kind of CSS elements are overridden.The direction of a language can be changed by going to
Configuration -> Languages and  clicking  the “edit” link for the language in question.
Testing for the directionality of the current language can be done in code using the following approach.

if (defined('LANGUAGE_RTL')  &&   $language->direction == LANGUAGE_RTL)  {
// Do  something.}

The reason this works is that the constant LANGUAGE_RTL is defined by the locale module, so if the locale module is not loaded, right-to-left language support is not available.

Figure 19-18. If the current language is a right-to-left language, an additional style sheet will be included if the additional style sheet exists.

Language Negotiation

Drupal implements most of the common ways of determining a user’s language so that when multiple languages are enabled on a Drupal site, the user’s preferred language is used. In the following sections, we will assume that the French translation of
Drupal hasbeen installed as described in the previous section. The way that Drupal determines the language setting is configuredat Configuration -> Languages under the Detection and  Selection tab. The relevant user interface is shown in Figure
19-19. Let’s examine each  ofthese options.

Figure 19-19. The possible settings  for language negotiation

Default
This is the default option and  the simplest one.  The language that is set as the default language is used for all users when
displaying pages. See Figure  19-17 to see the user interface in which the default language is specified.

User-Preferred Language
If more than one language is enabled, users will see the fieldset shown in Figure  19-20 when they edit their “My account”
pages.

Figure 19-20. Choosing a user-specific language for e-mail messages

The language that a user has chosen can be retrieved as follows:
// Retrieve user  3's  preferred language.
$account  = user_load(1);   // in  the  example I’m using  the  admin account
$language  = user_preferred_language($account);
If the user has not set a preferred language, the default language for the site will be returned. The result will be a language object (see the next section for more about the language object). When  the “Language negotiation” setting is set to None, theuser’s preferred language is used only for determining which language should be used for e-mail sent  from the site.
The user’s preferred language has no effect on the language used for page display when the “Language negotiation” setting
is set to None.

The Global $language Object
You can determine the current language programmatically by looking at the global $language variable, which is an object. Thevariable is initialized during the DRUPAL_BOOTSTRAP_LANGUAGE portion of bootstrap. You can see what  the object
looks likeby doing a var_dump():
global  $language; var_dump($language);
Results are shown here:
object(stdClass) (11) {
["language"]   => string(2)  "fr" ["name"] => string(6) "French" ["native"]   => string(9) "Français"["direction"] => string(1) "0" ["enabled"] => int(1) ["plurals"]         => string(1) "2" ["formula"] => string(6) "($n>1)" ["domain"]       => string(0) "" ["prefix"]   => string(2)  "fr" ["weight"] => string(1) "0
["javascript"]=> string(0)  ""}

The RFC 4646 language identifier (such as  fr in the previous example) can be retrieved by getting the language
property of the $language  of the $language object:
global  $language;
$lang  = $language->language;
Path  Prefix Only

When  language negotiation is set to Path  Prefix Only, there are only two possibilities. Either  a language path prefix is found
in the path, or the default language is used. For example, suppose you are creating a site that supports users in both English andFrench.English  is the default language for the site, but the French translation has also been installed and  enabled. Going to
Configuration -> Languages and clicking the “edit” link next to the French language will show  you the user interface
shown in Figure  19-21.  Notice that the “Path  prefix” field is set to fr. This value could be changed to any string.

Figure 19-21. User interface for the “Edit language” screen showing the “Path prefix” field

With the path prefix set to fr, Drupal will determine the current language by looking at the requested URL. The process is
shown in Figure  19-22.

Figure 19-22. Determination of language using the path prefix for French

Path  Prefix with Language Fallback

When  language negotiation is set to this setting, Drupal will first look at the path prefix. If a match is not made, the user’s
preferred language is checked by examining $user->language. If the user has not selected a preferred language, Drupal next
tries to determinethe user’s preferred language by looking at the Accept-language HTTP header in the browser’s HTTP
request. If the browser does  not specify a preferred language, the default language for the site is used. Assuming that English is the default language for the site,and  both French and  Hebrew are enabled, the process of language determination is shown inFigure  19-23.

Figure 19-23. Determination of language using “Path prefix with language fallback”

URL Only

When  language negotiation is set to this setting, Drupal will determine the current language by attempting to match the current URL with the language domain specified in the “Language domain” field of the “Edit language” page of a language (see
Figure  19-21). For example, with English  as the default language, specifying http://fr.example.com as the language
 domain for the French language would set the current language to French for users visiting http://fr.example.com/?q=node/2 and English  for usersvisiting   http://example.com/  ?q=node/2.