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

TranslationWrapper deprecated

class TranslationWrapper extends TranslatableMarkup (View source)

deprecated in drupal:8.0.0 and is removed from drupal:10.0.0. Use the \Drupal\Core\StringTranslation\TranslatableMarkup class instead.

Provides translatable string class.

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.

 from  TranslatableMarkup
protected array $options

The translation options.

 from  TranslatableMarkup
protected TranslationInterface $stringTranslation

The string translation service.

 from  TranslatableMarkup

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.

from  TranslatableMarkup
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|object
render()

Renders the object as a string.

from  ToStringTrait
string
getUntranslatedString()

Gets the untranslated string value stored in this translated string.

from  TranslatableMarkup
mixed
getOption(string $name)

Gets a specific option from this translated string.

from  TranslatableMarkup
array
getOptions()

Gets all options from this translated string.

from  TranslatableMarkup
array
getArguments()

Gets all arguments from this translated string.

from  TranslatableMarkup
__sleep()

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

from  TranslatableMarkup
TranslationInterface
getStringTranslation()

Gets the string translation service.

from  TranslatableMarkup

Details

at line 18
__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

in ToStringTrait at line 13
__toString()

Implements the magic __toString() method.

in TranslatableMarkup 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.

in ToStringTrait at line 41
abstract string|object render()

Renders the object as a string.

Return Value

string|object

The rendered string or an object implementing __toString().

in TranslatableMarkup at line 145
string getUntranslatedString()

Gets the untranslated string value stored in this translated string.

Return Value

string

The string stored in this wrapper.

in TranslatableMarkup 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.

in TranslatableMarkup at line 168
array getOptions()

Gets all options from this translated string.

Return Value

array

The array of options.

in TranslatableMarkup at line 178
array getArguments()

Gets all arguments from this translated string.

Return Value

array

The array of arguments.

in TranslatableMarkup at line 203
__sleep()

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

in TranslatableMarkup at line 213
protected TranslationInterface getStringTranslation()

Gets the string translation service.

Return Value

TranslationInterface

The string translation service.