679
679
* $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)));
682
* - @variable, which indicates that the text should be run through check_plain,
683
* to strip out HTML characters. Use this for any output that's displayed within
682
* - @variable, which indicates that the text should be run through
683
* check_plain, to escape HTML characters. Use this for any output that's
684
* displayed within a Drupal page.
686
686
* drupal_set_title($title = t("@name's blog", array('@name' => $account->name)));
689
* - %variable, which indicates that the string should be highlighted with
690
* theme_placeholder() which shows up by default as <em>emphasized</em>.
689
* - %variable, which indicates that the string should be HTML escaped and
690
* highlighted with theme_placeholder() which shows up by default as
691
* <em>emphasized</em>.
692
* watchdog('mail', t('%name-from sent %name-to an e-mail.', array('%name-from' => $user->name, '%name-to' => $account->name)));
693
* $message = t('%name-from sent %name-to an e-mail.', array('%name-from' => $user->name, '%name-to' => $account->name));
695
696
* When using t(), try to put entire sentences and strings in one t() call.
696
697
* This makes it easier for translators, as it provides context as to what
697
* each word refers to. HTML markup within translation strings is allowed,
698
* but should be avoided if possible. The exception is embedded links; link
699
* titles add additional context for translators so should be kept in the main
698
* each word refers to. HTML markup within translation strings is allowed, but
699
* should be avoided if possible. The exception are embedded links; link
700
* titles add a context for translators, so should be kept in the main string.
702
* Here is an example of an incorrect use if t():
702
* Here is an example of incorrect usage of t():
704
704
* $output .= t('<p>Go to the @contact-page.</p>', array('@contact-page' => l(t('contact page'), 'contact')));
721
721
* $output .= t("Don't click me.");
724
* Because t() is designed for handling code-based strings, in almost all
725
* cases, the actual string and not a variable must be passed through t().
727
* Extraction of translations is done based on the strings contained in t()
728
* calls. If a variable is passed through t(), the content of the variable
729
* cannot be extracted from the file for translation.
733
* $message = 'An error occurred.';
734
* drupal_set_message(t($message), 'error');
735
* $output .= t($message);
740
* $message = t('An error occurred.');
741
* drupal_set_message($message, 'error');
742
* $output .= $message;
745
* The only case in which variables can be passed safely through t() is when
746
* code-based versions of the same strings will be passed through t() (or
747
* otherwise extracted) elsewhere.
749
* In some cases, modules may include strings in code that can't use t()
750
* calls. For example, a module may use an external PHP application that
751
* produces strings that are loaded into variables in Drupal for output.
752
* In these cases, module authors may include a dummy file that passes the
753
* relevant strings through t(). This approach will allow the strings to be
756
* Sample external (non-Drupal) code:
759
* public $yesterday = 'Yesterday';
760
* public $today = 'Today';
761
* public $tomorrow = 'Tomorrow';
767
* // Dummy function included in example.potx.inc.
768
* function example_potx() {
774
* // No return value needed, since this is a dummy function.
778
* Having passed strings through t() in a dummy function, it is then
779
* okay to pass variables through t().
781
* Correct (if a dummy file was used):
783
* $time = new Time();
784
* $output .= t($time->today);
787
* However tempting it is, custom data from user input or other non-code
788
* sources should not be passed through t(). Doing so leads to the following
789
* problems and errors:
790
* - The t() system doesn't support updates to existing strings. When user
791
* data is updated, the next time it's passed through t() a new record is
792
* created instead of an update. The database bloats over time and any
793
* existing translations are orphaned with each update.
794
* - The t() system assumes any data it receives is in English. User data may
795
* be in another language, producing translation errors.
796
* - The "Built-in interface" text group in the locale system is used to
797
* produce translations for storage in .po files. When non-code strings are
798
* passed through t(), they are added to this text group, which is rendered
799
* inaccurate since it is a mix of actual interface strings and various user
800
* input strings of uncertain origin.
804
* $item = item_load();
805
* $output .= check_plain(t($item['title']));
808
* Instead, translation of these data can be done through the locale system,
809
* either directly or through helper functions provided by contributed
813
* During installation, st() is used in place of t(). Code that may be called
814
* during installation or during normal operation should use the get_t()
725
820
* A string containing the English string to translate.