Commit 6a208f85 authored by webchick's avatar webchick
Browse files

#338443 by jhodgdon, earnie, grendzy: Fixed various documentation issues with t().

parent 06585e6b
...@@ -1186,12 +1186,13 @@ function drupal_unpack($obj, $field = 'data') { ...@@ -1186,12 +1186,13 @@ function drupal_unpack($obj, $field = 'data') {
} }
/** /**
* Translate strings to the page language or a given language. * Translates a string to the current language or to a given language.
* *
* Human-readable text that will be displayed somewhere within a page should * All human-readable text that will be displayed on the site or sent to a user
* be run through the t() function. * should be passed through the t() function. This ensures that sites can be
* fully translated into other languages.
* *
* Examples: * Here are some examples of translating static text using t():
* @code * @code
* if (!$info || !$info['extension']) { * if (!$info || !$info['extension']) {
* form_set_error('picture_upload', t('The uploaded file was not an image.')); * form_set_error('picture_upload', t('The uploaded file was not an image.'));
...@@ -1203,95 +1204,85 @@ function drupal_unpack($obj, $field = 'data') { ...@@ -1203,95 +1204,85 @@ function drupal_unpack($obj, $field = 'data') {
* ); * );
* @endcode * @endcode
* *
* Any text within t() can be extracted by translators and changed into * In addition to translating static text, t() can handle text that should not
* the equivalent text in their native language. * be translated or that might change from time to time (such as link paths)
* * and dynamic text from variables, using special "placeholders". There are
* Special variables called "placeholders" are used to signal dynamic * three styles of placeholders:
* information in a string which should not be translated. Placeholders * - !variable: Indicates that the text should be inserted as-is. This is
* can also be used for text that may change from time to time (such as * useful for inserting variables into things like e-mail. Example:
* 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 * @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", array('absolute' => TRUE)))); * $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))));
* @endcode * @endcode
* * - @variable: Indicates that the text should be run through check_plain(), to
* - @variable, which indicates that the text should be run through * escape HTML characters. Use this for any output that is displayed within a
* check_plain, to escape HTML characters. Use this for any output that's * Drupal page. Example:
* displayed within a Drupal page.
* @code * @code
* drupal_set_title($title = t("@name's blog", array('@name' => format_username($account))), PASS_THROUGH); * drupal_set_title($title = t("@name's blog", array('@name' => format_username($account))), PASS_THROUGH);
* @endcode * @endcode
* * - %variable: Indicates that the string should be HTML-escaped and highlighted
* - %variable, which indicates that the string should be HTML escaped and * with theme_placeholder(), which shows up by default as <em>emphasized</em>.
* highlighted with theme_placeholder() which shows up by default as
* <em>emphasized</em>.
* @code * @code
* $message = t('%name-from sent %name-to an e-mail.', array('%name-from' => format_username($user), '%name-to' => format_username($account))); * $message = t('%name-from sent %name-to an e-mail.', array('%name-from' => format_username($user), '%name-to' => format_username($account)));
* @endcode * @endcode
* *
* When using t(), try to put entire sentences and strings in one t() call. * When using t(), try to put entire paragraphs in one t() call. This makes it
* This makes it easier for translators, as it provides context as to what * easier for translators, as it provides context as to what each word refers
* each word refers to. HTML markup within translation strings is allowed, but * to (and also allows translators to adjust word order, which may not be the
* should be avoided if possible. The exception are embedded links; link * same in all languages). HTML markup within translation strings is allowed,
* titles add a context for translators, so should be kept in the main string. * but should be avoided if possible. The exception is embedded links: link
* * titles add context for translators and need to be translated, so they should
* Here is an example of incorrect usage of t(): * be kept in the main string, while link URLs should be generated using
* @code * placeholders.
* $output .= t('<p>Go to the @contact-page.</p>', array('@contact-page' => l(t('contact page'), 'contact'))); * - Incorrect HTML in t():
* @endcode * @code
* * $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: * @endcode
* @code * - Correct HTML in t():
* $output .= '<p>' . t('Go to the <a href="@contact-page">contact page</a>.', array('@contact-page' => url('contact'))) . '</p>'; * @code
* @endcode * $output .= '<p>' . t('Go to the <a href="@contact-page">contact page</a>.', array('@contact-page' => url('contact'))) . '</p>';
* * @endcode
* Avoid escaping quotation marks wherever possible.
*
* Incorrect:
* @code
* $output .= t('Don\'t click me.');
* @endcode
*
* Correct:
* @code
* $output .= t("Don't click me.");
* @endcode
*
* Because t() is designed for handling code-based strings, in almost all
* cases, the actual string and not a variable must be passed through t().
*
* Extraction of translations is done based on the strings contained in t()
* calls. If a variable is passed through t(), the content of the variable
* cannot be extracted from the file for translation.
* *
* Incorrect: * Another thing that is helpful is to avoid escaping quotation marks wherever
* @code * possible, because it can be confusing to translation teams.
* $message = 'An error occurred.'; * - Less desirable quotation mark escaping:
* drupal_set_message(t($message), 'error'); * @code
* $output .= t($message); * $output .= t('Don\'t click me.');
* @endcode * @endcode
* - Better way to use quotation marks:
* @code
* $output .= t("Don't click me.");
* @endcode
* *
* Correct: * It is important that all translation uses the t() mechanism, because in
* @code * addition to actually translating the text at run-time, the t() function is
* $message = t('An error occurred.'); * also used by text-extraction routines to find text that needs to be
* drupal_set_message($message, 'error'); * translated, and build databases of text to be translated for translation
* $output .= $message; * teams. For that reason, you must put the actual string into the t() function,
* @endcode * in most cases, and not a variable.
* - Incorrect use of a variable in t():
* @code
* $message = 'An error occurred.';
* drupal_set_message(t($message), 'error');
* $output .= t($message);
* @endcode
* - Correct translation of a variable with t():
* @code
* $message = t('An error occurred.');
* drupal_set_message($message, 'error');
* $output .= $message;
* @endcode
* *
* The only case in which variables can be passed safely through t() is when * The only case in which variables can be passed safely through t() is when
* code-based versions of the same strings will be passed through t() (or * code-based versions of the same strings will be passed through t() (or
* otherwise extracted) elsewhere. * otherwise extracted) elsewhere.
* *
* Also, you cannot use t() early in the bootstrap process, prior to the
* DRUPAL_BOOTSTRAP_LANGUAGE phase. The language variables will not be
* initialized yet, so the string will not be translated into the correct
* language. Examples of places where t() cannot be used include:
* - In a PHP define() statement.
* - In a hook_boot() implementation.
*
* In some cases, modules may include strings in code that can't use t() * In some cases, modules may include strings in code that can't use t()
* calls. For example, a module may use an external PHP application that * calls. For example, a module may use an external PHP application that
* produces strings that are loaded into variables in Drupal for output. * produces strings that are loaded into variables in Drupal for output.
...@@ -1308,7 +1299,7 @@ function drupal_unpack($obj, $field = 'data') { ...@@ -1308,7 +1299,7 @@ function drupal_unpack($obj, $field = 'data') {
* } * }
* @endcode * @endcode
* *
* Sample dummy file. * Sample dummy file:
* @code * @code
* // Dummy function included in example.potx.inc. * // Dummy function included in example.potx.inc.
* function example_potx() { * function example_potx() {
...@@ -1322,9 +1313,7 @@ function drupal_unpack($obj, $field = 'data') { ...@@ -1322,9 +1313,7 @@ function drupal_unpack($obj, $field = 'data') {
* @endcode * @endcode
* *
* Having passed strings through t() in a dummy function, it is then * Having passed strings through t() in a dummy function, it is then
* okay to pass variables through t(). * possible to pass variables through t():
*
* Correct (if a dummy file was used):
* @code * @code
* $time = new Time(); * $time = new Time();
* $output .= t($time->today); * $output .= t($time->today);
...@@ -1334,7 +1323,7 @@ function drupal_unpack($obj, $field = 'data') { ...@@ -1334,7 +1323,7 @@ function drupal_unpack($obj, $field = 'data') {
* sources should not be passed through t(). Doing so leads to the following * sources should not be passed through t(). Doing so leads to the following
* problems and errors: * problems and errors:
* - The t() system doesn't support updates to existing strings. When user * - The t() system doesn't support updates to existing strings. When user
* data is updated, the next time it's passed through t() a new record is * data is updated, the next time it's passed through t(), a new record is
* created instead of an update. The database bloats over time and any * created instead of an update. The database bloats over time and any
* existing translations are orphaned with each update. * existing translations are orphaned with each update.
* - The t() system assumes any data it receives is in English. User data may * - The t() system assumes any data it receives is in English. User data may
...@@ -1344,6 +1333,9 @@ function drupal_unpack($obj, $field = 'data') { ...@@ -1344,6 +1333,9 @@ function drupal_unpack($obj, $field = 'data') {
* passed through t(), they are added to this text group, which is rendered * passed through t(), they are added to this text group, which is rendered
* inaccurate since it is a mix of actual interface strings and various user * inaccurate since it is a mix of actual interface strings and various user
* input strings of uncertain origin. * input strings of uncertain origin.
* Instead, translation of these data can be done through the locale system,
* either directly through hook_local() or through helper functions provided by
* contributed modules.
* *
* Incorrect: * Incorrect:
* @code * @code
...@@ -1351,16 +1343,9 @@ function drupal_unpack($obj, $field = 'data') { ...@@ -1351,16 +1343,9 @@ function drupal_unpack($obj, $field = 'data') {
* $output .= check_plain(t($item['title'])); * $output .= check_plain(t($item['title']));
* @endcode * @endcode
* *
* Instead, translation of these data can be done through the locale system,
* either directly or through helper functions provided by contributed
* modules.
* @see hook_locale()
*
* During installation, st() is used in place of t(). Code that may be called * During installation, st() is used in place of t(). Code that may be called
* during installation or during normal operation should use the get_t() * during installation or during normal operation should use the get_t()
* helper function. * helper function.
* @see st()
* @see get_t()
* *
* @param $string * @param $string
* A string containing the English string to translate. * A string containing the English string to translate.
...@@ -1369,15 +1354,16 @@ function drupal_unpack($obj, $field = 'data') { ...@@ -1369,15 +1354,16 @@ function drupal_unpack($obj, $field = 'data') {
* of any key in this array are replaced with the corresponding value. Based * 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: * on the first character of the key, the value is escaped and/or themed:
* - !variable: inserted as is * - !variable: inserted as is
* - @variable: escape plain text to HTML (check_plain) * - @variable: escape plain text to HTML (using check_plain())
* - %variable: escape text and theme as a placeholder for user-submitted * - %variable: escape text and theme as a placeholder for user-submitted
* content (check_plain + theme_placeholder) * content (using check_plain() + theme_placeholder())
* @param $options * @param $options
* An associative array of additional options, with the following keys: * An associative array of additional options, with the following keys:
* - 'langcode' (default to the current language) The language code to * - 'langcode' (defaults to the current language) The language code to
* translate to a language other than what is used to display the page. * translate to a language other than what is used to display the page.
* - 'context' (default to the empty context) The context the source string * - 'context' (defaults to the empty context) The context the source string
* belongs to. * belongs to.
*
* @return * @return
* The translated string. * The translated string.
* *
......
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