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