t
Definition
t($string, $args = array(), $langcode = NULL)
drupal-cvs/includes/common.inc, line 931
Description
Translate strings to the page language or a given language.
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", array('absolute' => TRUE))));
?>
- @variable, which indicates that the text should be run through check_plain, to escape 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)), PASS_THROUGH);
?>
- %variable, which indicates that the string should be HTML escaped and highlighted with theme_placeholder() which shows up by default as <em>emphasized</em>.
<?php
$message = 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 are embedded links; link titles add a context for translators, so should be kept in the main string.
Here is an example of incorrect usage of 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 = array(), $langcode = NULL) {
global $language;
static $custom_strings;
if (!isset($langcode)) {
$langcode = $language->language;
}
// First, check for an array of customized strings. If present, use the array
// *instead of* database lookups. This is a high performance way to provide a
// handful of string replacements. See settings.php for examples.
// Cache the $custom_strings variable to improve performance.
if (!isset($custom_strings[$langcode])) {
$custom_strings[$langcode] = variable_get('locale_custom_strings_' . $langcode, array());
}
// Custom strings work for English too, even if locale module is disabled.
if (isset($custom_strings[$langcode][$string])) {
$string = $custom_strings[$langcode][$string];
}
// Translate with locale module if enabled.
elseif (function_exists('locale') && $langcode != 'en') {
$string = locale($string, $langcode);
}
if (empty($args)) {
return $string;
}
else {
// Transform arguments before inserting them.
foreach ($args as $key => $value) {
switch ($key[0]) {
case '@':
// Escaped only.
$args[$key] = check_plain($value);
break;
case '%':
default:
// Escaped and placeholder.
$args[$key] = theme('placeholder', $value);
break;
case '!':
// Pass-through.
}
}
return strtr($string, $args);
}
}
?>