annotate core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 129ea1e6d783
children
rev   line source
Chris@0 1 <?php
Chris@0 2
Chris@0 3 namespace Drupal\Core\StringTranslation;
Chris@0 4
Chris@0 5 use Drupal\Component\Render\FormattableMarkup;
Chris@0 6 use Drupal\Component\Utility\ToStringTrait;
Chris@0 7
Chris@0 8 /**
Chris@0 9 * Provides translatable markup class.
Chris@0 10 *
Chris@0 11 * This object, when cast to a string, will return the formatted, translated
Chris@0 12 * string. Avoid casting it to a string yourself, because it is preferable to
Chris@0 13 * let the rendering system do the cast as late as possible in the rendering
Chris@0 14 * process, so that this object itself can be put, untranslated, into render
Chris@0 15 * caches and thus the cache can be shared between different language contexts.
Chris@0 16 *
Chris@0 17 * @see \Drupal\Component\Render\FormattableMarkup
Chris@0 18 * @see \Drupal\Core\StringTranslation\TranslationManager::translateString()
Chris@0 19 * @see \Drupal\Core\Annotation\Translation
Chris@0 20 */
Chris@0 21 class TranslatableMarkup extends FormattableMarkup {
Chris@0 22
Chris@0 23 use ToStringTrait;
Chris@0 24
Chris@0 25 /**
Chris@0 26 * The translated markup without placeholder replacements.
Chris@0 27 *
Chris@0 28 * @var string
Chris@0 29 */
Chris@0 30 protected $translatedMarkup;
Chris@0 31
Chris@0 32 /**
Chris@0 33 * The translation options.
Chris@0 34 *
Chris@0 35 * @var array
Chris@0 36 */
Chris@0 37 protected $options;
Chris@0 38
Chris@0 39 /**
Chris@0 40 * The string translation service.
Chris@0 41 *
Chris@0 42 * @var \Drupal\Core\StringTranslation\TranslationInterface
Chris@0 43 */
Chris@0 44 protected $stringTranslation;
Chris@0 45
Chris@0 46 /**
Chris@0 47 * Constructs a new class instance.
Chris@0 48 *
Chris@0 49 * When possible, use the
Chris@0 50 * \Drupal\Core\StringTranslation\StringTranslationTrait $this->t(). Otherwise
Chris@0 51 * create a new \Drupal\Core\StringTranslation\TranslatableMarkup object
Chris@0 52 * directly.
Chris@0 53 *
Chris@0 54 * Calling the trait's t() method or instantiating a new TranslatableMarkup
Chris@0 55 * object serves two purposes:
Chris@0 56 * - At run-time it translates user-visible text into the appropriate
Chris@0 57 * language.
Chris@0 58 * - Static analyzers detect calls to t() and new TranslatableMarkup, and add
Chris@0 59 * the first argument (the string to be translated) to the database of
Chris@0 60 * strings that need translation. These strings are expected to be in
Chris@0 61 * English, so the first argument should always be in English.
Chris@0 62 * To allow the site to be localized, it is important that all human-readable
Chris@0 63 * text that will be displayed on the site or sent to a user is made available
Chris@0 64 * in one of the ways supported by the
Chris@0 65 * @link https://www.drupal.org/node/322729 Localization API @endlink.
Chris@0 66 * See the @link https://www.drupal.org/node/322729 Localization API @endlink
Chris@0 67 * pages for more information, including recommendations on how to break up or
Chris@0 68 * not break up strings for translation.
Chris@0 69 *
Chris@0 70 * @section sec_translating_vars Translating Variables
Chris@0 71 * $string should always be an English literal string.
Chris@0 72 *
Chris@0 73 * $string should never contain a variable, such as:
Chris@0 74 * @code
Chris@0 75 * new TranslatableMarkup($text)
Chris@0 76 * @endcode
Chris@0 77 * There are several reasons for this:
Chris@0 78 * - Using a variable for $string that is user input is a security risk.
Chris@0 79 * - Using a variable for $string that has even guaranteed safe text (for
Chris@0 80 * example, user interface text provided literally in code), will not be
Chris@0 81 * picked up by the localization static text processor. (The parameter could
Chris@0 82 * be a variable if the entire string in $text has been passed into t() or
Chris@0 83 * new TranslatableMarkup() elsewhere as the first argument, but that
Chris@0 84 * strategy is not recommended.)
Chris@0 85 *
Chris@0 86 * It is especially important never to call new TranslatableMarkup($user_text)
Chris@0 87 * or t($user_text) where $user_text is some text that a user entered -- doing
Chris@0 88 * that can lead to cross-site scripting and other security problems. However,
Chris@0 89 * you can use variable substitution in your string, to put variable text such
Chris@0 90 * as user names or link URLs into translated text. Variable substitution
Chris@0 91 * looks like this:
Chris@0 92 * @code
Chris@0 93 * new TranslatableMarkup("@name's blog", array('@name' => $account->getDisplayName()));
Chris@0 94 * @endcode
Chris@0 95 * Basically, you can put placeholders like @name into your string, and the
Chris@0 96 * method will substitute the sanitized values at translation time. (See the
Chris@0 97 * Localization API pages referenced above and the documentation of
Chris@0 98 * \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
Chris@0 99 * for details about how to safely and correctly define variables in your
Chris@0 100 * string.) Translators can then rearrange the string as necessary for the
Chris@0 101 * language (e.g., in Spanish, it might be "blog de @name").
Chris@0 102 *
Chris@0 103 * @param string $string
Chris@0 104 * A string containing the English text to translate.
Chris@0 105 * @param array $arguments
Chris@0 106 * (optional) An associative array of replacements to make after
Chris@0 107 * translation. Based on the first character of the key, the value is
Chris@0 108 * escaped and/or themed. See
Chris@0 109 * \Drupal\Component\Render\FormattableMarkup::placeholderFormat() for
Chris@0 110 * details.
Chris@0 111 * @param array $options
Chris@0 112 * (optional) An associative array of additional options, with the following
Chris@0 113 * elements:
Chris@0 114 * - 'langcode' (defaults to the current language): A language code, to
Chris@0 115 * translate to a language other than what is used to display the page.
Chris@0 116 * - 'context' (defaults to the empty context): The context the source
Chris@0 117 * string belongs to.
Chris@0 118 * @param \Drupal\Core\StringTranslation\TranslationInterface $string_translation
Chris@0 119 * (optional) The string translation service.
Chris@0 120 *
Chris@0 121 * @throws \InvalidArgumentException
Chris@0 122 * Exception thrown when $string is not a string.
Chris@0 123 *
Chris@0 124 * @see \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
Chris@0 125 * @see \Drupal\Core\StringTranslation\StringTranslationTrait::t()
Chris@0 126 *
Chris@0 127 * @ingroup sanitization
Chris@0 128 */
Chris@0 129 public function __construct($string, array $arguments = [], array $options = [], TranslationInterface $string_translation = NULL) {
Chris@0 130 if (!is_string($string)) {
Chris@0 131 $message = $string instanceof TranslatableMarkup ? '$string ("' . $string->getUntranslatedString() . '") must be a string.' : '$string ("' . (string) $string . '") must be a string.';
Chris@0 132 throw new \InvalidArgumentException($message);
Chris@0 133 }
Chris@14 134 parent::__construct($string, $arguments);
Chris@0 135 $this->options = $options;
Chris@0 136 $this->stringTranslation = $string_translation;
Chris@0 137 }
Chris@0 138
Chris@0 139 /**
Chris@0 140 * Gets the untranslated string value stored in this translated string.
Chris@0 141 *
Chris@0 142 * @return string
Chris@0 143 * The string stored in this wrapper.
Chris@0 144 */
Chris@0 145 public function getUntranslatedString() {
Chris@0 146 return $this->string;
Chris@0 147 }
Chris@0 148
Chris@0 149 /**
Chris@0 150 * Gets a specific option from this translated string.
Chris@0 151 *
Chris@0 152 * @param string $name
Chris@0 153 * Option name.
Chris@0 154 *
Chris@0 155 * @return mixed
Chris@0 156 * The value of this option or empty string of option is not set.
Chris@0 157 */
Chris@0 158 public function getOption($name) {
Chris@0 159 return isset($this->options[$name]) ? $this->options[$name] : '';
Chris@0 160 }
Chris@0 161
Chris@0 162 /**
Chris@0 163 * Gets all options from this translated string.
Chris@0 164 *
Chris@0 165 * @return mixed[]
Chris@0 166 * The array of options.
Chris@0 167 */
Chris@0 168 public function getOptions() {
Chris@0 169 return $this->options;
Chris@0 170 }
Chris@0 171
Chris@0 172 /**
Chris@0 173 * Gets all arguments from this translated string.
Chris@0 174 *
Chris@0 175 * @return mixed[]
Chris@0 176 * The array of arguments.
Chris@0 177 */
Chris@0 178 public function getArguments() {
Chris@0 179 return $this->arguments;
Chris@0 180 }
Chris@0 181
Chris@0 182 /**
Chris@0 183 * Renders the object as a string.
Chris@0 184 *
Chris@0 185 * @return string
Chris@0 186 * The translated string.
Chris@0 187 */
Chris@0 188 public function render() {
Chris@0 189 if (!isset($this->translatedMarkup)) {
Chris@0 190 $this->translatedMarkup = $this->getStringTranslation()->translateString($this);
Chris@0 191 }
Chris@0 192
Chris@0 193 // Handle any replacements.
Chris@0 194 if ($args = $this->getArguments()) {
Chris@0 195 return $this->placeholderFormat($this->translatedMarkup, $args);
Chris@0 196 }
Chris@0 197 return $this->translatedMarkup;
Chris@0 198 }
Chris@0 199
Chris@0 200 /**
Chris@0 201 * Magic __sleep() method to avoid serializing the string translator.
Chris@0 202 */
Chris@0 203 public function __sleep() {
Chris@0 204 return ['string', 'arguments', 'options'];
Chris@0 205 }
Chris@0 206
Chris@0 207 /**
Chris@0 208 * Gets the string translation service.
Chris@0 209 *
Chris@0 210 * @return \Drupal\Core\StringTranslation\TranslationInterface
Chris@0 211 * The string translation service.
Chris@0 212 */
Chris@0 213 protected function getStringTranslation() {
Chris@0 214 if (!$this->stringTranslation) {
Chris@0 215 $this->stringTranslation = \Drupal::service('string_translation');
Chris@0 216 }
Chris@0 217
Chris@0 218 return $this->stringTranslation;
Chris@0 219 }
Chris@0 220
Chris@0 221 /**
Chris@0 222 * Returns the string length.
Chris@0 223 *
Chris@0 224 * @return int
Chris@0 225 * The length of the string.
Chris@0 226 */
Chris@0 227 public function count() {
Chris@17 228 return mb_strlen($this->render());
Chris@0 229 }
Chris@0 230
Chris@0 231 }