1. class
  2. Drupal
  3. \
  4. Core
  5. \
  6. StringTranslation
  7. \
  8. TranslatableMarkup

TranslatableMarkup

class TranslatableMarkup extends FormattableMarkup (View source)

Provides translatable markup class.

This object, when cast to a string, will return the formatted, translated string. Avoid casting it to a string yourself, because it is preferable to let the rendering system do the cast as late as possible in the rendering process, so that this object itself can be put, untranslated, into render caches and thus the cache can be shared between different language contexts.

Traits

ToStringTrait

Wraps __toString in a trait to avoid some fatals.

Properties

protected string $string

The string containing placeholders.

 from  FormattableMarkup
protected array $arguments

The arguments to replace placeholders with.

 from  FormattableMarkup
protected string $translatedMarkup

The translated markup without placeholder replacements.
protected array $options

The translation options.
protected TranslationInterface $stringTranslation

The string translation service.

Methods

__construct(string $string, array $arguments = [], array $options = [], TranslationInterface $string_translation = NULL)

Constructs a new class instance.

__toString()

Implements the magic __toString() method.

from  ToStringTrait
int
count()

Returns the string length.

string
jsonSerialize()

Returns a representation of the object for use in JSON serialization.

from  FormattableMarkup
static string
placeholderFormat(string $string, array $args)

Replaces placeholders in a string with values.

from  FormattableMarkup
static string
placeholderEscape(string|MarkupInterface $value)

Escapes a placeholder replacement value if needed.

from  FormattableMarkup
_die()

For test purposes, wrap die() in an overridable method.

from  ToStringTrait
string
render()

Renders the object as a string.

string
getUntranslatedString()

Gets the untranslated string value stored in this translated string.

mixed
getOption(string $name)

Gets a specific option from this translated string.

array
getOptions()

Gets all options from this translated string.

array
getArguments()

Gets all arguments from this translated string.

__sleep()

Magic __sleep() method to avoid serializing the string translator.

TranslationInterface
getStringTranslation()

Gets the string translation service.

Details

at line 129
__construct(string $string, array $arguments = [], array $options = [], TranslationInterface $string_translation = NULL)

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

Parameters

string $string

A string containing placeholders. The string itself will not be escaped, any unsafe content must be in $args and inserted via placeholders.
array $arguments

An array with placeholder replacements, keyed by placeholder. See \Drupal\Component\Render\FormattableMarkup::placeholderFormat() for additional information about placeholders.
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.
TranslationInterface $string_translation

(optional) The string translation service.

Exceptions

InvalidArgumentException

See also

FormattableMarkup::placeholderFormat
StringTranslationTrait::t

in ToStringTrait at line 13
__toString()

Implements the magic __toString() method.

at line 227
int count()

Returns the string length.

Return Value

int

The length of the string.

in FormattableMarkup at line 119
string jsonSerialize()

Returns a representation of the object for use in JSON serialization.

Return Value

string

The safe string content.

in FormattableMarkup at line 196
static protected string placeholderFormat(string $string, array $args)

Replaces placeholders in a string with values.

Parameters

string $string

A string containing placeholders. The string itself is expected to be safe and correct HTML. Any unsafe content must be in $args and inserted via placeholders.
array $args

An associative array of replacements. Each array key should be the same as a placeholder in $string. The corresponding value should be a string or an object that implements \Drupal\Component\Render\MarkupInterface. The value replaces the placeholder in $string. Sanitization and formatting will be done before replacement. The type of sanitization and formatting depends on the first character of the key:

  • @variable: When the placeholder replacement value is:
    • A string, the replaced value in the returned string will be sanitized using \Drupal\Component\Utility\Html::escape().
    • A MarkupInterface object, the replaced value in the returned string will not be sanitized.
    • A MarkupInterface object cast to a string, the replaced value in the returned string be forcibly sanitized using \Drupal\Component\Utility\Html::escape(). @code $this->placeholderFormat('This will force HTML-escaping of the replacement value: @text', ['@text' => (string) $safe_string_interface_object)); @endcode Use this placeholder as the default choice for anything displayed on the site, but not within HTML attributes, JavaScript, or CSS. Doing so is a security risk.
  • %variable: Use when the replacement value is to be wrapped in tags. A call like: @code $string = "%output_text"; $arguments = ['%output_text' => 'text output here.']; $this->placeholderFormat($string, $arguments); @endcode makes the following HTML code: @code text output here. @endcode As with @variable, do not use this within HTML attributes, JavaScript, or CSS. Doing so is a security risk.
  • :variable: Return value is escaped with \Drupal\Component\Utility\Html::escape() and filtered for dangerous protocols using UrlHelper::stripDangerousProtocols(). Use this when using the "href" attribute, ensuring the attribute value is always wrapped in quotes: @code // Secure (with quotes): $this->placeholderFormat('@variable', [':url' => $url, '@variable' => $variable]); // Insecure (without quotes): $this->placeholderFormat('@variable', [':url' => $url, '@variable' => $variable]); @endcode When ":variable" comes from arbitrary user input, the result is secure, but not guaranteed to be a valid URL (which means the resulting output could fail HTML validation). To guarantee a valid URL, use Url::fromUri($user_input)->toString() (which either throws an exception or returns a well-formed URL) before passing the result into a ":variable" placeholder.

Return Value

string

A formatted HTML string with the placeholders replaced.

See also

TranslatableMarkup
PluralTranslatableMarkup
Html::escape
UrlHelper::stripDangerousProtocols
Url::fromUri

in FormattableMarkup at line 261
static protected string placeholderEscape(string|MarkupInterface $value)

Escapes a placeholder replacement value if needed.

Parameters

string|MarkupInterface $value

A placeholder replacement value.

Return Value

string

The properly escaped replacement value.

in ToStringTrait at line 31
protected _die()

For test purposes, wrap die() in an overridable method.

at line 188
string render()

Renders the object as a string.

Return Value

string

The translated string.

at line 145
string getUntranslatedString()

Gets the untranslated string value stored in this translated string.

Return Value

string

The string stored in this wrapper.

at line 158
mixed getOption(string $name)

Gets a specific option from this translated string.

Parameters

string $name

Option name.

Return Value

mixed

The value of this option or empty string of option is not set.

at line 168
array getOptions()

Gets all options from this translated string.

Return Value

array

The array of options.

at line 178
array getArguments()

Gets all arguments from this translated string.

Return Value

array

The array of arguments.

at line 203
__sleep()

Magic __sleep() method to avoid serializing the string translator.

at line 213
protected TranslationInterface getStringTranslation()

Gets the string translation service.

Return Value

TranslationInterface

The string translation service.