Go to the @contact-page.
', array('@contact-page' => l(t('contact page'), 'contact'))); - * @endcode - * - Correct HTML in t(): - * @code - * $output .= '' . t('Go to the contact page.', array('@contact-page' => url('contact'))) . '
'; - * @endcode - * - * Another thing that is helpful is to avoid escaping quotation marks wherever - * possible, because it can be confusing to translation teams. - * - Less desirable quotation mark escaping: - * @code - * $output .= t('Don\'t click me.'); - * @endcode - * - Better way to use quotation marks: - * @code - * $output .= t("Don't click me."); - * @endcode - * - * It is important that all translation uses the t() mechanism, because in - * addition to actually translating the text at run-time, the t() function is - * also used by text-extraction routines to find text that needs to be - * translated, and build databases of text to be translated for translation - * teams. For that reason, you must put the actual string into the t() function, - * 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 + * same in all languages). + * + * @subsection html HTML tags + * + * HTML markup within translation strings is allowed, but should usually be + * avoided if possible. The exception is embedded links: link titles add context + * for translators and need to be translated, so they should be kept in the main + * string, while the link URLs should use placeholders. + * + * Incorrect HTML in t(): + * @code + * $output .= t('Go to the @contact-page.
', array('@contact-page' => l(t('contact page'), 'contact'))); + * @endcode + * + * Correct HTML in t(): + * @code + * $output .= '' . t('Go to the contact page.', array('@contact-page' => url('contact'))) . '
'; + * @endcode + * + * One exception to the rule of using an embedded link title: if the link title + * text is translated elsewhere as a separate string, it may be desirable to use + * a placeholder for the link text. For example, if you are linking to a + * specific permission on the Permissions page, you would use a placeholder for + * the permission name, so that that permission name gets translated in exactly + * the same way. Example: + * @code + * $description = t('Customizing the dashboard requires the !permission-name permission.', + * array( + * '!permission-name' => t('Administer blocks'), + * 'permission-url' => url('admin/people/permissions', array('fragment' => 'module-block')), + )); + * @endcode + * + * @subsection quotes Quotation marks + * + * It is helpful to avoid escaping quotation marks wherever possible, because it + * can be confusing to translation teams. For instance, rather than calling + * @code $output .= t('Don\'t click me.'); @endcode, call + * @code $output .= t("Don't click me."); @endcode. + * + * @subsection variables Actual strings, not variables + * + * As mentioned above, text-extraction mechanisms examine t() calls to build the + * database of text that needs to be translated. For that reason, you must put + * the actual string to be translated into the t() function, in most cases, and + * not a variable. Here is an INCORRECT usage example: + * @code + * $message = 'An error occurred.'; + * drupal_set_message(t($message), 'error'); + * $output .= t($message); + * @endcode + * Here is the correct usage: + * @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 * code-based versions of the same strings will be passed through t() (or * otherwise extracted) elsewhere. * - * Also, you cannot use t() early in the bootstrap process, prior to the + * @subsection early Places you cannot use t() + * + * 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() - * calls. For example, a module may use an external PHP application that - * produces strings that are loaded into variables in Drupal for output. - * In these cases, module authors may include a dummy file that passes the - * relevant strings through t(). This approach will allow the strings to be - * extracted. + * 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() + * helper function. + * + * @subsection external Translating strings from external code * - * Sample external (non-Drupal) code: + * 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 produces + * strings that are loaded into variables in Drupal for output. In these cases, + * module authors may include a dummy file that passes the relevant strings + * through t(). This approach will allow the strings to be extracted. For + * example, if you have this external code: * @code - * class Time { - * public $yesterday = 'Yesterday'; - * public $today = 'Today'; - * public $tomorrow = 'Tomorrow'; - * } + * class Time { + * public $yesterday = 'Yesterday'; + * public $today = 'Today'; + * public $tomorrow = 'Tomorrow'; + * } * @endcode - * - * Sample dummy file: + * You could define this dummy file: * @code - * // Dummy function included in example.potx.inc. - * function example_potx() { - * $strings = array( - * t('Yesterday'), - * t('Today'), - * t('Tomorrow'), - * ); - * // No return value needed, since this is a dummy function. - * } + * // Dummy function included in example.potx.inc. + * function example_potx() { + * $strings = array( + * t('Yesterday'), + * t('Today'), + * t('Tomorrow'), + * ); + * } * @endcode - * * Having passed strings through t() in a dummy function, it is then * possible to pass variables through t(): * @code - * $time = new Time(); - * $output .= t($time->today); + * $time = new Time(); + * $output .= t($time->today); * @endcode * + * @subsection user Text from user input + * * However tempting it is, custom data from user input or other non-code * sources should not be passed through t(). Doing so leads to the following * problems and errors: @@ -1370,35 +1408,30 @@ * inaccurate since it is a mix of actual interface strings and various user * 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: + * either directly through hook_locale() or through helper functions provided by + * contributed modules. Here is an INCORRECT example: * @code - * $item = item_load(); - * $output .= check_plain(t($item['title'])); + * $item = item_load(); + * $output .= check_plain(t($item['title'])); * @endcode * - * 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() - * helper function. - * * @param $string * A string containing the English string to translate. * @param $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 (using check_plain()) - * - %variable: escape text and theme as a placeholder for user-submitted - * content (using check_plain() + drupal_placeholder()) + * An associative array of replacements to make after translation. Occurrences + * in $string 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: Insert as is. + * - @variable: Escape plain text to HTML using check_plain(). + * - %variable: Escape text and theme as a placeholder for user-submitted + * content, using drupal_placeholder(). * @param $options - * An associative array of additional options, with the following keys: - * - 'langcode' (defaults to the current language) The language code to - * translate to a language other than what is used to display the page. - * - 'context' (defaults to the empty context) The context the source string - * belongs to. + * An associative array of additional options, with the following elements: + * - 'langcode' (defaults to the current language): The language code to + * translate to a language other than what is used to display the page. + * - 'context' (defaults to the empty context): The context the source string + * belongs to. * * @return * The translated string.