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

PluralTranslatableMarkup

class PluralTranslatableMarkup extends TranslatableMarkup (View source)

A class to hold plural translatable markup.

Traits

ToStringTrait

Wraps __toString in a trait to avoid some fatals.

Constants

deprecated DELIMITER

The delimiter used to split plural strings.

This is the ETX (End of text) character and is used as a minimal means to separate singular and plural variants in source and translation text. It was found to be the most compatible delimiter for the supported databases.

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
protected int $count

The item count to display.
protected string $translatedString

The already translated string.

Methods

__construct(int $count, string $singular, string $plural, array $args = [], array $options = [], TranslationInterface $string_translation = NULL)

Constructs a new PluralTranslatableMarkup object.

__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
render()

Renders the object as a string.

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.

TranslationInterface
getStringTranslation()

Gets the string translation service.

from  TranslatableMarkup
static PluralTranslatableMarkup
createFromTranslatedString(int $count, string $translated_string, array $args = [], array $options = [])

Constructs a new class instance from already translated markup.

int
getPluralIndex()

Gets the plural index through the gettext formula.

Details

at line 68
__construct(int $count, string $singular, string $plural, array $args = [], array $options = [], TranslationInterface $string_translation = NULL)

Constructs a new PluralTranslatableMarkup object.

Parses values passed into this class through the format_plural() function in Drupal and handles an optional context for the string.

Parameters

int $count

The item count to display.
string $singular

The string for the singular case. Make sure it is clear this is singular, to ease translation (e.g. use "1 new comment" instead of "1 new"). Do not use @count in the singular string.
string $plural

The string for the plural case. Make sure it is clear this is plural, to ease translation. Use @count in place of the item count, as in "@count new comments".
array $args

(optional) An array with placeholder replacements, keyed by placeholder. See \Drupal\Component\Render\FormattableMarkup::placeholderFormat() for additional information about placeholders. Note that you do not need to include @count in this array; this replacement is done automatically for the plural cases.
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.

See also

FormattableMarkup::placeholderFormat

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 118
string jsonSerialize()

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

Return Value

string

The safe string content.

in FormattableMarkup at line 194
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 264
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 110
string render()

Renders the object as a string.

Return Value

string

The translated string.

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.

at line 168
__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.

at line 98
static PluralTranslatableMarkup createFromTranslatedString(int $count, string $translated_string, array $args = [], array $options = [])

Constructs a new class instance from already translated markup.

This method ensures that the string is pluralized correctly. As opposed to the __construct() method, this method is designed to be invoked with a string already translated (such as with configuration translation).

Parameters

int $count

The item count to display.
string $translated_string

The already translated string.
array $args

An associative array of replacements to make after translation. Instances of any key in this array are replaced with the corresponding value. Based on the first character of the key, the value is escaped and/or themed. See \Drupal\Component\Render\FormattableMarkup. Note that you do not need to include @count in this array; this replacement is done automatically for the plural cases.
array $options

An associative array of additional options. See t() for allowed keys.

Return Value

PluralTranslatableMarkup

A PluralTranslatableMarkup object.

at line 152
protected int getPluralIndex()

Gets the plural index through the gettext formula.

Return Value

int