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 }
|