Commit 91158a97 authored by drumm's avatar drumm

#79407 by webchick. Improved documentation for t().

parent f84f1d2a
......@@ -619,18 +619,84 @@ function locale_initialize() {
/**
* 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:
* @code
* 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'),
* );
* @endcode
*
* 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 that may change from time to time
* (such as link paths) to be changed without requiring updates to translations.
*
* For example:
* @code
* $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')));
* @endcode
*
* 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.
* @code
* $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)));
* @endcode
*
* - @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.
* @code
* drupal_set_title($title = t("@name's blog", array('@name' => $account->name)));
* @endcode
*
* - %variable, which indicates that the string should be highlighted with
* theme_placeholder() which shows up by default as <em>emphasized</em>.
* @code
* watchdog('mail', t('%name-from sent %name-to an e-mail.', array('%name-from' => $user->name, '%name-to' => $account->name)));
* @endcode
*
* When using t(), try to put entire sentences and strings in one t() call.
* This makes it easier for translators. HTML markup within translation strings
* is acceptable, if necessary. The suggested syntax for a link embedded
* within a translation string is:
* 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():
* @code
* $output .= t('<p>Go to the @contact-page.</p>', array('@contact-page' => l(t('contact page'), 'contact')));
* @endcode
*
* Here is an example of t() used correctly:
* @code
* $output .= '<p>'. t('Go to the <a href="@contact-page">contact page</a>.', array('@contact-page' => url('contact'))) .'</p>';
* @endcode
*
* Also avoid escaping quotation marks wherever possible.
*
* Incorrect:
* @code
* $output .= t('Don\'t click me.');
* @endcode
*
* Correct:
* @code
* $msg = t('You must log in below or <a href="@url">create a new
* account</a> before viewing the next page.', array('@url'
* => url('user/register')));
* $output .= t("Don't click me.");
* @endcode
* We suggest the same syntax for links to other sites. This makes it easy to
* change link URLs if needed (which happens often) without requiring updates
* to translations.
*
* @param $string
* A string containing the English string to translate.
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment