TranslationInterface.php 4.01 KB
Newer Older
1 2 3 4 5 6 7 8 9
<?php

/**
 * @file
 * Contains \Drupal\Core\StringTranslation\TranslationInterface.
 */

namespace Drupal\Core\StringTranslation;

10 11 12 13 14
/**
 * Interface for the translation.manager translation service.
 *
 * @ingroup i18n
 */
15 16 17 18 19
interface TranslationInterface {

  /**
   * Translates a string to the current language or to a given language.
   *
20 21 22 23
   * Never call translate($user_text) where $user_text is text that a user
   * entered; doing so can lead to cross-site scripting and other security
   * problems.
   *
24 25 26 27 28
   * @param string $string
   *   A string containing the English string to translate.
   * @param array $args
   *   An associative array of replacements to make after translation. Based
   *   on the first character of the key, the value is escaped and/or themed.
29
   *   See \Drupal\Component\Utility\SafeMarkup::format() for details.
30 31 32 33 34 35
   * @param array $options
   *   An associative array of additional options, with the following elements:
   *   - 'langcode': The language code to translate to a language other than
   *      what is used to display the page.
   *   - 'context': The context the source string belongs to.
   *
36
   * @return \Drupal\Core\StringTranslation\TranslatableString
37 38
   *   The translated string.
   *
39
   * @see \Drupal\Component\Utility\SafeMarkup::format()
40 41 42
   */
  public function translate($string, array $args = array(), array $options = array());

43
  /**
44
   * Translates a TranslatableString object to a string.
45
   *
46 47
   * @param \Drupal\Core\StringTranslation\TranslatableString $translated_string
   *   A TranslatableString object.
48 49 50 51
   *
   * @return string
   *   The translated string.
   */
52
  public function translateString(TranslatableString $translated_string);
53

54 55 56
  /**
   * Formats a string containing a count of items.
   *
57 58 59 60
   * This function ensures that the string is pluralized correctly. Since
   * TranslationInterface::translate() is called by this function, make sure not
   * to pass already-localized strings to it. See
   * PluralTranslatableString::createFromTranslatedString() for that.
61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88
   *
   * For example:
   * @code
   *   $output = $string_translation->formatPlural($node->comment_count, '1 comment', '@count comments');
   * @endcode
   *
   * Example with additional replacements:
   * @code
   *   $output = $string_translation->formatPlural($update_count,
   *     'Changed the content type of 1 post from %old-type to %new-type.',
   *     'Changed the content type of @count posts from %old-type to %new-type.',
   *     array('%old-type' => $info->old_type, '%new-type' => $info->new_type));
   * @endcode
   *
   * @param int $count
   *   The item count to display.
   * @param string $singular
   *   The string for the singular case. Make sure it is clear this is singular,
   *   to ease translation (e.g. use "1 new comment" instead of "1 new"). Do not
   *   use @count in the singular string.
   * @param string $plural
   *   The string for the plural case. Make sure it is clear this is plural, to
   *   ease translation. Use @count in place of the item count, as in
   *   "@count new comments".
   * @param array $args
   *   An associative array of replacements to make after translation. Instances
   *   of any key in this array are replaced with the corresponding value.
   *   Based on the first character of the key, the value is escaped and/or
89
   *   themed. See \Drupal\Component\Utility\SafeMarkup::format(). Note that you do
90 91
   *   not need to include @count in this array; this replacement is done
   *   automatically for the plural cases.
92 93 94
   * @param array $options
   *   An associative array of additional options. See t() for allowed keys.
   *
95
   * @return \Drupal\Core\StringTranslation\PluralTranslatableString
96 97
   *   A translated string.
   *
98
   * @see \Drupal\Core\StringTranslation\TranslationInterface::translate()
99
   * @see t()
100
   * @see \Drupal\Component\Utility\SafeMarkup::format()
101
   * @see \Drupal\Core\StringTranslation\PluralTranslatableString::createFromTranslatedString()
102 103 104
   */
  public function formatPlural($count, $singular, $plural, array $args = array(), array $options = array());

105
}