diff --git a/core/includes/bootstrap.inc b/core/includes/bootstrap.inc
index 65a62d7..44bc083 100644
--- a/core/includes/bootstrap.inc
+++ b/core/includes/bootstrap.inc
@@ -258,56 +258,11 @@ function drupal_get_path($type, $name) {
 /**
  * Translates a string to the current language or to a given language.
  *
- * The t() function serves two purposes. First, at run-time it translates
- * user-visible text into the appropriate language. Second, various mechanisms
- * that figure out what text needs to be translated work off t() -- the text
- * inside t() calls is added to the database of strings to be translated.
- * These strings are expected to be in English, so the first argument should
- * always be in English. To enable a fully-translatable site, it is important
- * that all human-readable text that will be displayed on the site or sent to
- * a user is passed through the t() function, or a related function. See the
- * @link https://www.drupal.org/node/322729 Localization API @endlink pages for
- * more information, including recommendations on how to break up or not
- * break up strings for translation.
- *
- * @section sec_translating_vars Translating Variables
- * You should never use t() to translate variables, such as calling t($text)
- * unless the text that the variable holds has been passed through t()
- * elsewhere (e.g., $text is one of several translated literal strings in an
- * array). It is especially important never to call t($user_text) where
- * $user_text is some text that a user entered - doing that can lead to
- * cross-site scripting and other security problems. However, you can use
- * variable substitution in your string, to put variable text such as user
- * names or link URLs into translated text. Variable substitution looks like
- * this:
- * @code
- * $text = t("@name's blog", array('@name' => $account->getDisplayName()));
- * @endcode
- * Basically, you can put variables like @name into your string, and t() will
- * substitute their sanitized values at translation time. (See the
- * Localization API pages referenced above and the documentation of
- * \Drupal\Component\Utility\SafeMarkup::format() for details about how to
- * define variables in your string.). Translators can then rearrange the string
- * as necessary for the language (e.g., in Spanish, it might be "blog de
- * @name").
- *
- * @param $string
- *   A string containing the English string to translate.
- * @param $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.
- *   See \Drupal\Component\Utility\SafeMarkup::format() for details.
- * @param $options
- *   An associative array of additional options, with the following elements:
- *   - 'langcode' (defaults to the current language): The language code to
- *     translate to a language other than what is used to display the page.
- *   - 'context' (defaults to the empty context): The context the source string
- *     belongs to.
- *
- * @return \Drupal\Core\StringTranslation\TranslatableMarkup
- *   An object that, when cast to a string, will yield the translated string.
+ * See \Drupal\Core\StringTranslation\TranslationInterface::translate() for
+ * the function parameter and return value details, important security
+ * information, and usage guidelines.
  *
- * @see \Drupal\Component\Utility\SafeMarkup::format()
+ * @see \Drupal\Core\StringTranslation\TranslationInterface::translate()
  * @ingroup sanitization
  */
 function t($string, array $args = array(), array $options = array()) {
diff --git a/core/lib/Drupal/Core/StringTranslation/StringTranslationTrait.php b/core/lib/Drupal/Core/StringTranslation/StringTranslationTrait.php
index 53e1f6f..551d76a 100644
--- a/core/lib/Drupal/Core/StringTranslation/StringTranslationTrait.php
+++ b/core/lib/Drupal/Core/StringTranslation/StringTranslationTrait.php
@@ -36,11 +36,11 @@
   /**
    * Translates a string to the current language or to a given language.
    *
-   * See the t() documentation for details.
+   * See \Drupal\Core\StringTranslation\TranslationInterface::translate() for
+   * the function parameter and return value details, important security
+   * information, and usage guidelines.
    *
-   * Never call $this->t($user_text) where $user_text is text that a user
-   * entered; doing so can lead to cross-site scripting and other security
-   * problems.
+   * @see \Drupal\Core\StringTranslation\TranslationInterface::translate()
    */
   protected function t($string, array $args = array(), array $options = array()) {
     return $this->getStringTranslation()->translate($string, $args, $options);
diff --git a/core/lib/Drupal/Core/StringTranslation/TranslationInterface.php b/core/lib/Drupal/Core/StringTranslation/TranslationInterface.php
index 1944ecb..79c51c5 100644
--- a/core/lib/Drupal/Core/StringTranslation/TranslationInterface.php
+++ b/core/lib/Drupal/Core/StringTranslation/TranslationInterface.php
@@ -17,26 +17,69 @@
   /**
    * Translates a string to the current language or to a given language.
    *
-   * 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.
+   * Never call this translate() method directly. In order for strings to be
+   * localized, the you must use the method
+   * \Drupal\Core\StringTranslation\StringTranslationTrait::t(), by using the
+   * trait and calling it like $this->t(). Or, when in procedural code, call the
+   * function t().
+   *
+   * The t() function serves two purposes. First, at run-time it translates
+   * user-visible text into the appropriate language. Second, various mechanisms
+   * that figure out what text needs to be translated work off t() -- the text
+   * inside t() calls is added to the database of strings to be translated.
+   * These strings are expected to be in English, so the first argument should
+   * always be in English. To enable a fully-translatable site, it is important
+   * that all human-readable text that will be displayed on the site or sent to
+   * a user is passed through the t() function, or a related function. See the
+   * @link https://www.drupal.org/node/322729 Localization API @endlink pages
+   * for more information, including recommendations on how to break up or not
+   * break up strings for translation.
+   *
+   * @section sec_translating_vars Translating Variables
+   * You should never use t() to translate variables, such as calling t($text),
+   * for two reasons:
+   * - calling it on a variable that is user input is a security risk, and
+   * - calling it on a variable that has even guaranteed safe text, for example,
+   *   user interface text provided literally in code, will not be picked up by
+   *   the localization static text processor. (Unless the text that the
+   *   variable holds has been passed through t() elsewhere. But that strategy
+   *   is not recommended. It is better to call t() on literal strings.)
+   *
+   * It is especially important never to call t($user_text) where $user_text is
+   * some text that a user entered - doing that can lead to cross-site scripting
+   * and other security problems. However, you can use variable substitution in
+   * your string, to put variable text such as user names or link URLs into
+   * translated text. Variable substitution looks like this:
+   * @code
+   * $text = t("@name's blog", array('@name' => $account->getDisplayName()));
+   * @endcode
+   * Basically, you can put variables like @name into your string, and t() will
+   * substitute their sanitized values at translation time. (See the
+   * Localization API pages referenced above and the documentation of
+   * \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
+   * for details about how to safely and correctly define variables in your
+   * string.) Translators can then rearrange the string as necessary for the
+   * language (e.g., in Spanish, it might be "blog de @name").
    *
    * @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.
-   *   See \Drupal\Component\Utility\SafeMarkup::format() for details.
+   *   See \Drupal\Component\Render\FormattableMarkup::placeholderFormat() for
+   *   details.
    * @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.
+   *   - 'langcode' (defaults to the current language): The language code to
+   *     translate to a language other than what is used to display the page.
+   *   - 'context' (defaults to the empty context): The context the source string
+   *     belongs to.
    *
    * @return \Drupal\Core\StringTranslation\TranslatableMarkup
    *   An object that, when cast to a string, will yield the translated string.
    *
-   * @see \Drupal\Component\Utility\SafeMarkup::format()
+   * @see \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
+   * @ingroup sanitization
    */
   public function translate($string, array $args = array(), array $options = array());