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

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 4c8ae668cc8c
children
rev   line source
Chris@0 1 <?php
Chris@0 2
Chris@0 3 namespace Drupal\Core\StringTranslation;
Chris@0 4
Chris@0 5 /**
Chris@0 6 * Wrapper methods for \Drupal\Core\StringTranslation\TranslationInterface.
Chris@0 7 *
Chris@0 8 * Using this trait will add t() and formatPlural() methods to the class. These
Chris@0 9 * must be used for every translatable string, similar to how procedural code
Chris@0 10 * must use the global functions t() and \Drupal::translation()->formatPlural().
Chris@0 11 * This allows string extractor tools to find translatable strings.
Chris@0 12 *
Chris@0 13 * If the class is capable of injecting services from the container, it should
Chris@0 14 * inject the 'string_translation' service and assign it to
Chris@0 15 * $this->stringTranslation.
Chris@0 16 *
Chris@0 17 * @see \Drupal\Core\StringTranslation\TranslationInterface
Chris@0 18 * @see container
Chris@0 19 *
Chris@0 20 * @ingroup i18n
Chris@0 21 */
Chris@0 22 trait StringTranslationTrait {
Chris@0 23
Chris@0 24 /**
Chris@0 25 * The string translation service.
Chris@0 26 *
Chris@0 27 * @var \Drupal\Core\StringTranslation\TranslationInterface
Chris@0 28 */
Chris@0 29 protected $stringTranslation;
Chris@0 30
Chris@0 31 /**
Chris@0 32 * Translates a string to the current language or to a given language.
Chris@0 33 *
Chris@0 34 * See \Drupal\Core\StringTranslation\TranslatableMarkup::__construct() for
Chris@0 35 * important security information and usage guidelines.
Chris@0 36 *
Chris@0 37 * In order for strings to be localized, make them available in one of the
Chris@0 38 * ways supported by the
Chris@0 39 * @link https://www.drupal.org/node/322729 Localization API @endlink. When
Chris@0 40 * possible, use the \Drupal\Core\StringTranslation\StringTranslationTrait
Chris@0 41 * $this->t(). Otherwise create a new
Chris@0 42 * \Drupal\Core\StringTranslation\TranslatableMarkup object.
Chris@0 43 *
Chris@0 44 * @param string $string
Chris@0 45 * A string containing the English text to translate.
Chris@0 46 * @param array $args
Chris@0 47 * (optional) An associative array of replacements to make after
Chris@0 48 * translation. Based on the first character of the key, the value is
Chris@0 49 * escaped and/or themed. See
Chris@0 50 * \Drupal\Component\Render\FormattableMarkup::placeholderFormat() for
Chris@0 51 * details.
Chris@0 52 * @param array $options
Chris@0 53 * (optional) An associative array of additional options, with the following
Chris@0 54 * elements:
Chris@0 55 * - 'langcode' (defaults to the current language): A language code, to
Chris@0 56 * translate to a language other than what is used to display the page.
Chris@0 57 * - 'context' (defaults to the empty context): The context the source
Chris@0 58 * string belongs to. See the
Chris@0 59 * @link i18n Internationalization topic @endlink for more information
Chris@0 60 * about string contexts.
Chris@0 61 *
Chris@0 62 * @return \Drupal\Core\StringTranslation\TranslatableMarkup
Chris@0 63 * An object that, when cast to a string, returns the translated string.
Chris@0 64 *
Chris@0 65 * @see \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
Chris@0 66 * @see \Drupal\Core\StringTranslation\TranslatableMarkup::__construct()
Chris@0 67 *
Chris@0 68 * @ingroup sanitization
Chris@0 69 */
Chris@0 70 protected function t($string, array $args = [], array $options = []) {
Chris@0 71 return new TranslatableMarkup($string, $args, $options, $this->getStringTranslation());
Chris@0 72 }
Chris@0 73
Chris@0 74 /**
Chris@0 75 * Formats a string containing a count of items.
Chris@0 76 *
Chris@0 77 * @see \Drupal\Core\StringTranslation\TranslationInterface::formatPlural()
Chris@0 78 */
Chris@0 79 protected function formatPlural($count, $singular, $plural, array $args = [], array $options = []) {
Chris@0 80 return new PluralTranslatableMarkup($count, $singular, $plural, $args, $options, $this->getStringTranslation());
Chris@0 81 }
Chris@0 82
Chris@0 83 /**
Chris@0 84 * Returns the number of plurals supported by a given language.
Chris@0 85 *
Chris@0 86 * @see \Drupal\locale\PluralFormulaInterface::getNumberOfPlurals()
Chris@0 87 */
Chris@0 88 protected function getNumberOfPlurals($langcode = NULL) {
Chris@0 89 if (\Drupal::hasService('locale.plural.formula')) {
Chris@0 90 return \Drupal::service('locale.plural.formula')->getNumberOfPlurals($langcode);
Chris@0 91 }
Chris@0 92 // We assume 2 plurals if Locale's services are not available.
Chris@0 93 return 2;
Chris@0 94 }
Chris@0 95
Chris@0 96 /**
Chris@0 97 * Gets the string translation service.
Chris@0 98 *
Chris@0 99 * @return \Drupal\Core\StringTranslation\TranslationInterface
Chris@0 100 * The string translation service.
Chris@0 101 */
Chris@0 102 protected function getStringTranslation() {
Chris@0 103 if (!$this->stringTranslation) {
Chris@0 104 $this->stringTranslation = \Drupal::service('string_translation');
Chris@0 105 }
Chris@0 106
Chris@0 107 return $this->stringTranslation;
Chris@0 108 }
Chris@0 109
Chris@0 110 /**
Chris@0 111 * Sets the string translation service to use.
Chris@0 112 *
Chris@0 113 * @param \Drupal\Core\StringTranslation\TranslationInterface $translation
Chris@0 114 * The string translation service.
Chris@0 115 *
Chris@0 116 * @return $this
Chris@0 117 */
Chris@0 118 public function setStringTranslation(TranslationInterface $translation) {
Chris@0 119 $this->stringTranslation = $translation;
Chris@0 120
Chris@0 121 return $this;
Chris@0 122 }
Chris@0 123
Chris@0 124 }