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