public function TranslatableMarkup::__construct in Drupal 8

Same name and namespace in other branches

9 core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php \Drupal\Core\StringTranslation\TranslatableMarkup::__construct()

Constructs a new class instance.

When possible, use the \Drupal\Core\StringTranslation\StringTranslationTrait $this->t(). Otherwise create a new \Drupal\Core\StringTranslation\TranslatableMarkup object directly.

Calling the trait's t() method or instantiating a new TranslatableMarkup object serves two purposes:

At run-time it translates user-visible text into the appropriate language.
Static analyzers detect calls to t() and new TranslatableMarkup, and add the first argument (the string to be translated) to the database of strings that need translation. These strings are expected to be in English, so the first argument should always be in English.

To allow the site to be localized, it is important that all human-readable text that will be displayed on the site or sent to a user is made available in one of the ways supported by the Localization API. See the Localization API pages for more information, including recommendations on how to break up or not break up strings for translation.

Translating Variables

$string should always be an English literal string.

$string should never contain a variable, such as:

new TranslatableMarkup($text);

There are several reasons for this:

Using a variable for $string that is user input is a security risk.
Using a variable for $string that has even guaranteed safe text (for example, user interface text provided literally in code), will not be picked up by the localization static text processor. (The parameter could be a variable if the entire string in $text has been passed into t() or new TranslatableMarkup() elsewhere as the first argument, but that strategy is not recommended.)

It is especially important never to call new TranslatableMarkup($user_text) or 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:

new TranslatableMarkup("@name's blog", array(
  '@name' => $account
    ->getDisplayName(),
));

Basically, you can put placeholders like @name into your string, and the method will substitute the sanitized values at translation time. (See the Localization API pages referenced above and the documentation of \Drupal\Component\Render\FormattableMarkup::placeholderFormat() for details about how to safely and correctly 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").

Parameters

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

array $arguments: (optional) An associative array of replacements to make after translation. Based on the first character of the key, the value is escaped and/or themed. See \Drupal\Component\Render\FormattableMarkup::placeholderFormat() for details.

array $options: (optional) An associative array of additional options, with the following elements:

'langcode' (defaults to the current language): A 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.

\Drupal\Core\StringTranslation\TranslationInterface $string_translation: (optional) The string translation service.

Throws

\InvalidArgumentException Exception thrown when $string is not a string.

Overrides FormattableMarkup::__construct

File

core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php, line 129

Class

TranslatableMarkup: Provides translatable markup class.

Namespace

Drupal\Core\StringTranslation

Code

public function __construct($string, array $arguments = [], array $options = [], TranslationInterface $string_translation = NULL) {
  if (!is_string($string)) {
    $message = $string instanceof TranslatableMarkup ? '$string ("' . $string
      ->getUntranslatedString() . '") must be a string.' : '$string ("' . (string) $string . '") must be a string.';
    throw new \InvalidArgumentException($message);
  }
  parent::__construct($string, $arguments);
  $this->options = $options;
  $this->stringTranslation = $string_translation;
}

You are here