1<?php 2 3namespace Drupal\Core\StringTranslation; 4 5/** 6 * Interface for the translation.manager translation service. 7 * 8 * @ingroup i18n 9 */ 10interface 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\Render\FormattableMarkup. 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\Render\FormattableMarkup 108 * @see \Drupal\Core\StringTranslation\PluralTranslatableMarkup::createFromTranslatedString() 109 */ 110 public function formatPlural($count, $singular, $plural, array $args = [], array $options = []); 111 112} 113