Standard Practices for using Drupal Translate Function – t()

Multi lingual sites is a desired feature for sites targeting audiences of multiple countries or of more than one linguistic groups for example my first experience with the module was translating the Wanderlust Festival website for audiences in Quebec, where French and English are national languages. For Drupal there are many features which streamline the process. We will go into some of the standard translation techniques. In a later post I will go into identifying and translating certain hard to target strings such as those in complex views.

The Translate Function:

When we are dealing with content in templates for pages/nodes/content-types, etc. some strings are hardcoded in these tpl.php files.

Drupal provides us a smart way to let its template engine know which strings to consider for translation and which strings to treat as constant literals – that don’t need translation.

There is a translate function, also known as t function or t(). Anything passed inside this function is processed and considered for translation before getting passed to html content. Example: t(“text for translation”).

String literals that are not enclosed in this function are considered as constant strings and are passed as is into the html content. Example: Anything that doesn’t require translation – like Names of places, persons, etc. (in case we are translating in the same script like English to French)

The prototype of the translate function is:

t($string, array $args = array(), array $options = array());

Here, $string is the variable containing the English string to translate.
$args is an associative array of replacements to make. Occurrences in $string of any key in $args are replaced with the corresponding value, after optional sanitization and formatting. The type of sanitization and formatting depends on the first character of the key:

• @variable: Value is inserted as plain text.
• %variable: This makes it display as emphasized text.
• !variable: Inserted as is, with no sanitization or formatting. Only use this for text that has already been prepared for HTML display (for example, user-supplied text that has already been run through check_plain() previously, or is expected to contain some limited HTML tags and has already been run through filter_xss() previously).

This is an example to demonstrate above three keys:

t("This is my text", array( '@This' => 'yeh', '%is my' => 'hi', '!text' =>  'text'));

It will translate from “This is my text” to “yeh hi text”.
The simplest call to t() looks like this:
t(“This is my text”);

Where to call t() function ?

• Any string that is a name, url, address passed in t() should specify the translated string also either from the admin panel or in the translate function call itself by passing through $args array.
• In case you are making a Form with form API, it is a good practice to pass the title, placeholder and labels in t() function. Example:$form['title'] = array(
'#type' => 'textfield',
'#title' => t('Subject'),
'#required' => TRUE,
);
• In case your are using a php field in views, it is advisable to output any text in t(), except for dates or dynamic data.

Where not to call t() function ?

It is NOT advisable to use t() in following scenarios:

• t($text);
  unless the text that the variable holds has been passed through t() elsewhere (e.g., $text is one of several translated literal strings in an array).
• It is especially important never to call
  t($user_text);
  where $user_text is some text that a user entered – doing that can lead to cross-site scripting and other security problems.

However, you can use variable substitution in your string, to put variable text such as user names or link URLs into translated text. Variable substitution looks like this:

$text = t("@name's blog", array('@name' => format_username($account)));

Basically, you can put variables like @name into your string, and t() will substitute their sanitized values at translation time. Translators can then rearrange the string as necessary for the language (e.g., in Spanish, it might be “blog de @name”).