www.aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/StringTranslation/TranslationInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\StringTranslation;
   4
   5 /**
   6  * Interface for the translation.manager translation service.
   7  *
   8  * @ingroup i18n
   9  */
  10 interface TranslationInterface {
  11
  12   /**
  13    * Translates a string to the current language or to a given language.
  14    *
  15    * Never call this translate() method directly. In order for strings to be
  16    * localized, make them available in one of the ways supported by the
  17    * @link https://www.drupal.org/node/322729 Localization API @endlink. When
  18    * possible, use the \Drupal\Core\StringTranslation\StringTranslationTrait
  19    * $this->t(). Otherwise create a new
  20    * \Drupal\Core\StringTranslation\TranslatableMarkup object.
  21    *
  22    * @param string $string
  23    *   A string containing the English text to translate.
  24    * @param array $args
  25    *   (optional) An associative array of replacements to make after
  26    *   translation. Based on the first character of the key, the value is
  27    *   escaped and/or themed. See
  28    *   \Drupal\Component\Render\FormattableMarkup::placeholderFormat() for
  29    *   details.
  30    * @param array $options
  31    *   (optional) An associative array of additional options, with the following
  32    *   elements:
  33    *   - 'langcode' (defaults to the current language): A language code, to
  34    *     translate to a language other than what is used to display the page.
  35    *   - 'context' (defaults to the empty context): The context the source
  36    *     string belongs to. See the
  37    *     @link i18n Internationalization topic @endlink for more information
  38    *     about string contexts.
  39    *
  40    * @return \Drupal\Core\StringTranslation\TranslatableMarkup
  41    *   An object that, when cast to a string, returns the translated string.
  42    *
  43    * @see \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
  44    * @see \Drupal\Core\StringTranslation\TranslatableMarkup::__construct()
  45    *
  46    * @ingroup sanitization
  47    */
  48   public function translate($string, array $args = [], array $options = []);
  49
  50   /**
  51    * Translates a TranslatableMarkup object to a string.
  52    *
  53    * @param \Drupal\Core\StringTranslation\TranslatableMarkup $translated_string
  54    *   A TranslatableMarkup object.
  55    *
  56    * @return string
  57    *   The translated string.
  58    */
  59   public function translateString(TranslatableMarkup $translated_string);
  60
  61   /**
  62    * Formats a string containing a count of items.
  63    *
  64    * This function ensures that the string is pluralized correctly. Since
  65    * TranslationInterface::translate() is called by this function, make sure not
  66    * to pass already-localized strings to it. See
  67    * PluralTranslatableMarkup::createFromTranslatedString() for that.
  68    *
  69    * For example:
  70    * @code
  71    *   $output = $string_translation->formatPlural($node->comment_count, '1 comment', '@count comments');
  72    * @endcode
  73    *
  74    * Example with additional replacements:
  75    * @code
  76    *   $output = $string_translation->formatPlural($update_count,
  77    *     'Changed the content type of 1 post from %old-type to %new-type.',
  78    *     'Changed the content type of @count posts from %old-type to %new-type.',
  79    *     array('%old-type' => $info->old_type, '%new-type' => $info->new_type));
  80    * @endcode
  81    *
  82    * @param int $count
  83    *   The item count to display.
  84    * @param string $singular
  85    *   The string for the singular case. Make sure it is clear this is singular,
  86    *   to ease translation (e.g. use "1 new comment" instead of "1 new"). Do not
  87    *   use @count in the singular string.
  88    * @param string $plural
  89    *   The string for the plural case. Make sure it is clear this is plural, to
  90    *   ease translation. Use @count in place of the item count, as in
  91    *   "@count new comments".
  92    * @param array $args
  93    *   An associative array of replacements to make after translation. Instances
  94    *   of any key in this array are replaced with the corresponding value.
  95    *   Based on the first character of the key, the value is escaped and/or
  96    *   themed. See \Drupal\Component\Utility\SafeMarkup::format(). Note that you do
  97    *   not need to include @count in this array; this replacement is done
  98    *   automatically for the plural cases.
  99    * @param array $options
 100    *   An associative array of additional options. See t() for allowed keys.
 101    *
 102    * @return \Drupal\Core\StringTranslation\PluralTranslatableMarkup
 103    *   A translated string.
 104    *
 105    * @see \Drupal\Core\StringTranslation\TranslationInterface::translate()
 106    * @see t()
 107    * @see \Drupal\Component\Utility\SafeMarkup::format()
 108    * @see \Drupal\Core\StringTranslation\PluralTranslatableMarkup::createFromTranslatedString()
 109    */
 110   public function formatPlural($count, $singular, $plural, array $args = [], array $options = []);
 111
 112 }