t
Definition
t($string, $args = 0)
includes/common.inc, line 736
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:
<?php
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:
<?php
$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.
<?php
$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.
<?php
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>.
<?php
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():
<?php
$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:
<?php
$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:
<?php
$output .= t('Don\'t click me.');
?>
Correct:
<?php
$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
<?php
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);
}
}
?>