Home › API reference

Definition

t($string, $args = 0)
drupal/includes/common.inc, line 728

Description

Translate strings to the current locale.

All human-readable text that will be displayed somewhere within a page should be run through the t() function.

Examples:

if (!$info || !$info['extension']) {
form_set_error('picture_upload', t('The uploaded file was not an image.'));
}


$form['submit'] = array(
'#type' => 'submit',
'#value' => t('Log in'),
);

Any text within t() can be extracted by translators and changed into the equivalent text in their native language.

Special variables called "placeholders" are used to signal dynamic information in a string which should not be translated. Placeholders can also be used for text that may change from time to time (such as link paths) to be changed without requiring updates to translations.

For example:

$output = t('There are currently %members and %visitors online.', array(
'%members' => format_plural($total_users, '1 user', '@count users'),
'%visitors' => format_plural($guests->count, '1 guest', '@count guests')));

There are three styles of placeholders:

  • !variable, which indicates that the text should be inserted as-is. This is useful for inserting variables into things like e-mail.

$message[] = t("If you don't want to receive such e-mails, you can change your settings at !url.", array('!url' => url("user/$account->uid", NULL, NULL, TRUE)));

  • @variable, which indicates that the text should be run through check_plain, to strip out HTML characters. Use this for any output that's displayed within a Drupal page.

drupal_set_title($title = t("@name's blog", array('@name' => $account->name)));

  • %variable, which indicates that the string should be highlighted with theme_placeholder() which shows up by default as <em>emphasized</em>.

watchdog('mail', t('%name-from sent %name-to an e-mail.', array('%name-from' => $user->name, '%name-to' => $account->name)));

When using t(), try to put entire sentences and strings in one t() call. This makes it easier for translators, as it provides context as to what each word refers to. HTML markup within translation strings is allowed, but should be avoided if possible. The exception is embedded links; link titles add additional context for translators so should be kept in the main string.

Here is an example of an incorrect use if t():

$output .= t('<p>Go to the @contact-page.</p>', array('@contact-page' => l(t('contact page'), 'contact')));

Here is an example of t() used correctly:

$output .= '<p>'. t('Go to the <a href="@contact-page">contact page</a>.', array('@contact-page' => url('contact'))) .'</p>';

Also avoid escaping quotation marks wherever possible.

Incorrect:

$output .= t('Don\'t click me.');

Correct:

$output .= t("Don't click me.");

Parameters

$string A string containing the English string to translate.

$args An associative array of replacements to make after translation. Incidences of any key in this array are replaced with the corresponding value. Based on the first character of the key, the value is escaped and/or themed:

  • !variable: inserted as is
  • @variable: escape plain text to HTML (check_plain)
  • %variable: escape text and theme as a placeholder for user-submitted content (check_plain + theme_placeholder)

Return value

The translated string.

Code

function t($string, $args = 0) {
  global $locale;
  if (function_exists('locale') && $locale != 'en') {
    $string = locale($string);
  }
  if (!$args) {
    return $string;
  }
  else {
    // Transform arguments before inserting them
    foreach ($args as $key => $value) {
      switch ($key[0]) {
        // Escaped only
        case '@':
          $args[$key] = check_plain($value);
        break;
        // Escaped and placeholder
        case '%':
        default:
          $args[$key] = theme('placeholder', $value);
          break;
        // Pass-through
        case '!':
      }
    }
    return strtr($string, $args);
  }
}