Drupal 8  8.0.2
TranslatableMarkup Class Reference
Inheritance diagram for TranslatableMarkup:

Protected Attributes

 $string
 
 $translatedMarkup
 
 $options
 
 $stringTranslation
 
- Protected Attributes inherited from FormattableMarkup
 $arguments = []
 

into your string, and the

Constructs a new class instance.

When possible, use the $this->t(). Otherwise create a new 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 method will substitute the sanitized values at translation time. (See the Localization API pages referenced above and the documentation of ::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$stringA 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 ::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.
Exceptions
\InvalidArgumentExceptionException thrown when $string is not a string.
See Also
::placeholderFormat()
t()
 __construct ($string, array $arguments=array(), array $options=array(), TranslationInterface $string_translation=NULL)
 
 getUntranslatedString ()
 
 getOption ($name)
 
 getOptions ()
 
 getArguments ()
 
 render ()
 
 __sleep ()
 
 count ()
 
 getStringTranslation ()
 

Additional Inherited Members

- Public Member Functions inherited from FormattableMarkup
 __construct ($string, array $arguments)
 
 __toString ()
 
 count ()
 
 jsonSerialize ()
 
- Static Protected Member Functions inherited from FormattableMarkup
static placeholderFormat ($string, array $args)
 
static placeholderEscape ($value)
 

Detailed Description

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.

See Also
::translateString()

Member Function Documentation

__sleep ( )

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

count ( )

Returns the string length.

Returns
int The length of the string.

References TranslatableMarkup\render(), and Unicode\strlen().

Referenced by PluralTranslatableMarkup\__construct(), PluralTranslatableMarkup\getPluralIndex(), and PluralTranslatableMarkup\render().

Here is the call graph for this function:

Here is the caller graph for this function:

getArguments ( )

Gets all arguments from this translated string.

Returns
mixed[] The array of arguments.

Referenced by PluralTranslatableMarkup\render(), and TranslatableMarkup\render().

Here is the caller graph for this function:

getOption (   $name)

Gets a specific option from this translated string.

Parameters
string$nameOption name.
Returns
mixed The value of this option or empty string of option is not set.

Referenced by PluralTranslatableMarkup\getPluralIndex().

Here is the caller graph for this function:

getOptions ( )

Gets all options from this translated string.

Returns
mixed[] The array of options.

Referenced by TranslationManager\translateString().

Here is the caller graph for this function:

getStringTranslation ( )
protected

Gets the string translation service.

Returns
The string translation service.

References Drupal\service().

Referenced by PluralTranslatableMarkup\render(), and TranslatableMarkup\render().

Here is the call graph for this function:

Here is the caller graph for this function:

getUntranslatedString ( )

Gets the untranslated string value stored in this translated string.

Returns
string The string stored in this wrapper.

Referenced by UnitTestCase\getStringTranslationStub(), TranslationManager\translateString(), and TestTranslationManager\translateString().

Here is the caller graph for this function:

render ( )

Renders the object as a string.

Returns
string The translated string.

References TranslatableMarkup\getArguments(), TranslatableMarkup\getStringTranslation(), and FormattableMarkup\placeholderFormat().

Referenced by TranslatableMarkup\count().

Here is the call graph for this function:

Here is the caller graph for this function:


The documentation for this class was generated from the following file: