1 bootstrap.inc t($string, array $args = array(), array $options = array())

Translates a string to the current language or to a given language.

The t() function serves two purposes. First, at run-time it translates user-visible text into the appropriate language. Second, various mechanisms that figure out what text needs to be translated work off t() -- the text inside t() calls is added to the database of strings to be translated. These strings are expected to be in English, so the first argument should always be in English. To enable a fully-translatable site, it is important that all human-readable text that will be displayed on the site or sent to a user is passed through the t() function, or a related function. See the Localization API pages for more information, including recommendations on how to break up or not break up strings for translation.

Translating Variables

You should never use t() to translate variables, such as calling

t($text);

, unless the text that the variable holds has been passed through t() elsewhere (e.g., $text is one of several translated literal strings in an array). It is especially important never to call

t($user_text);

, where $user_text is some text that a user entered - doing that can lead to cross-site scripting and other security problems. However, you can use variable substitution in your string, to put variable text such as user names or link URLs into translated text. Variable substitution looks like this:

$text = t("@name's blog", array('@name' => user_format_name($account)));

Basically, you can put variables like "@name" into your string, and t() will substitute their sanitized values at translation time. (See the Localization API pages referenced above and the documentation of format_string() for details about how to define variables in your string.) Translators can then rearrange the string as necessary for the language (e.g., in Spanish, it might be "blog de @name").

Use During Installation Phase

During the Backdrop installation phase, some resources used by t() wil not be available to code that needs localization. See st() and get_t() for alternatives.

String context

Matching source strings are normally only translated once, and the same translation is used everywhere that has a matching string. However, in some cases, a certain English source string needs to have multiple translations. One example of this is the string "May", which could be used as either a full month name or a 3-letter abbreviated month. In other languages where the month name for May has more than 3 letters, you would need to provide two different translations (one for the full name and one abbreviated), and the correct form would need to be chosen, depending on how "May" is being used. To facilitate this, the "May" string should be provided with two different contexts in the $options parameter when calling t(). For example:

t('May', array(), array('context' => 'Long month name')
t('May', array(), array('context' => 'Abbreviated month name')

See https://localize.drupal.org/node/2109 for more information.

Parameters

$string: A string containing the English string to translate.

$args: An associative array of replacements to make. Occurrences in $string of any key in $args are replaced with the corresponding value, after optional sanitization and formatting. The type of sanitization and formatting depends on the first character of the key:

  • @variable: Escaped to HTML using check_plain(). Use this as the default choice for anything displayed on a page on the site.
  • %variable: Escaped to HTML and formatted using backdrop_placeholder(), which makes it display as <em>emphasized</em> text.
  • !variable: Inserted as is, with no sanitization or formatting. Only use this for text that has already been prepared for HTML display (for example, user-supplied text that has already been run through check_plain() previously, or is expected to contain some limited HTML tags and has already been run through filter_xss() previously).

$options: 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): A string giving the context that the source string belongs to. See @ref sec_context above for more information.

Return value

The translated string.:

See also

st()

get_t()

format_string()

Related topics

Sanitization functions Functions to sanitize values.

File

core/includes/bootstrap.inc, line 2009
Functions that need to be loaded on every Backdrop request.

Code

function t($string, array $args = array(), array $options = array()) {
  global $language;

  // Use the advanced backdrop_static() pattern, since this is called very often.
  static $backdrop_static_fast;
  if (!isset($backdrop_static_fast)) {
    $backdrop_static_fast['t'] = &backdrop_static(__FUNCTION__, array());
  }
  $custom_strings = &$backdrop_static_fast['t']['custom_strings'];
  $translate_english = &$backdrop_static_fast['t']['translate_english'];

  // Merge in default.
  if (empty($options['langcode'])) {
    $options['langcode'] = isset($language->langcode) ? $language->langcode : LANGUAGE_SYSTEM;
  }
  if (empty($options['context'])) {
    $options['context'] = '';
  }

  // Locale module may not have been enabled, so we check for NULL value here
  // and statically cache the result for performance.
  if (!isset($translate_english)) {
    try {
      $translate_english = (function_exists('config_get') && config_get('locale.settings', 'translate_english')) ? TRUE : FALSE;
    }
    catch (ConfigException $e) {
      $translate_english = FALSE;
    }
  }

  // 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[$options['langcode']])) {
    $custom_strings[$options['langcode']] = settings_get('locale_custom_strings_' . $options['langcode'], array());
  }
  // Custom strings work for English too, even if locale module is disabled.
  if (isset($custom_strings[$options['langcode']][$options['context']][$string])) {
    $string = $custom_strings[$options['langcode']][$options['context']][$string];
  }
  // Translate with locale module if enabled.
  elseif ($options['langcode'] != LANGUAGE_SYSTEM && ($options['langcode'] != 'en' || $translate_english) && function_exists('locale')) {
    $string = locale($string, $options['context'], $options['langcode']);
  }
  if (empty($args)) {
    return $string;
  }
  else {
    return format_string($string, $args);
  }
}