diff --git a/core/includes/bootstrap.inc b/core/includes/bootstrap.inc
index a673771..1e8e287 100644
--- a/core/includes/bootstrap.inc
+++ b/core/includes/bootstrap.inc
@@ -269,7 +269,7 @@ function drupal_get_path($type, $name) {
  * important security information and usage guidelines.
  *
  * @param string $string
- *   A string containing the English string to translate.
+ *   A string containing the English text to translate.
  * @param array $args
  *   (optional) An associative array of replacements to make after
  *   translation. Based on the first character of the key, the value is
@@ -279,13 +279,13 @@ function drupal_get_path($type, $name) {
  * @param array $options
  *   (optional) An associative array of additional options, with the following
  *   elements:
- *   - 'langcode' (defaults to the current language): The language code to
+ *   - 'langcode' (defaults to the current language): A 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.
+ *   - '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.
+ *   An object that, when cast to a string, returns the translated string.
  *
  * @see \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
  * @see \Drupal\Core\StringTranslation\StringTranslationTrait::t()
diff --git a/core/lib/Drupal/Core/StringTranslation/StringTranslationTrait.php b/core/lib/Drupal/Core/StringTranslation/StringTranslationTrait.php
index d9d900f..80b0682 100644
--- a/core/lib/Drupal/Core/StringTranslation/StringTranslationTrait.php
+++ b/core/lib/Drupal/Core/StringTranslation/StringTranslationTrait.php
@@ -47,7 +47,7 @@
    * \Drupal\Core\StringTranslation\TranslatableMarkup object.
    *
    * @param string $string
-   *   A string containing the English string to translate.
+   *   A string containing the English text to translate.
    * @param array $args
    *   (optional) An associative array of replacements to make after
    *   translation. Based on the first character of the key, the value is
@@ -57,13 +57,13 @@
    * @param array $options
    *   (optional) An associative array of additional options, with the following
    *   elements:
-   *   - 'langcode' (defaults to the current language): The language code to
+   *   - 'langcode' (defaults to the current language): A 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.
+   *   An object that, when cast to a string, returns the translated string.
    *
    * @see \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
    * @see \Drupal\Core\StringTranslation\TranslatableMarkup::__construct()
diff --git a/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php b/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php
index 382c8ad..ca88459 100644
--- a/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php
+++ b/core/lib/Drupal/Core/StringTranslation/TranslatableMarkup.php
@@ -13,17 +13,13 @@
 /**
  * Provides translatable markup class.
  *
- * Formats a translatable string for HTML display by replacing variable
- * placeholders. Handles an optional context for the string. This object, when
- * cast to a string, will yield the translated string.
- *
- * This is useful for using translation in very low level subsystems like entity
- * definition and stream wrappers.
- *
- * This class delays translation until rendering.
+ * This object, when cast to a string, will return formatted, translated string.
+ * Avoid casting it to a string yourself, because it is preferable to let the
+ * rendering system do the cast as late as possible in the rendering process, so
+ * that this object itself can be put, untranslated, into render caches and thus
+ * the cache can be shared between different language contexts.
  *
  * @see \Drupal\Component\Render\FormattableMarkup
- * @see \Drupal\Core\StringTranslation\TranslationManager::translate()
  * @see \Drupal\Core\StringTranslation\TranslationManager::translateString()
  * @see \Drupal\Core\Annotation\Translation
  */
@@ -63,46 +59,52 @@ class TranslatableMarkup extends FormattableMarkup {
    * Constructs a new class instance.
    *
    * If your class uses \Drupal\Core\StringTranslation\StringTranslationTrait,
-   * use $this->t() instead of creating this object. But, in a class that has
-   * t(), in a static method, create this object to do translation.
-   *
-   * Doing new TranslatableMarkup(), or calling 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 the string -- the text inside the call 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 allow the site to be localized, it is important that all
+   * use $this->t() instead of creating this object. But, even a class that has
+   * t() might have in a static method, in that static method it  will need to
+   * create this object to do translation.
+   *
+   * Calling the trait's t() method or instantiating a new TranslatableMarkup
+   * object serves two purposes:
+   * - at run-time it translates user-visible text into the appropriate
+   *   language.
+   * - static analyzers detect calls to t() and new TranslatableMarkup, and add
+   *   the first argument (the string to be translated) to the database of
+   *   strings that need translation. These strings are expected to be in
+   *   English, so the first argument should always be in English.
+   * To allow the site to be localized, 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
+   * made available in one of the ways supported by the
+   * @link https://www.drupal.org/node/322729 Localization API @endlink.
+   * 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
+   * $string should always contain, at least in part, an English literal.
+   *
    * $string should never contain a variable, such as:
    * @code
    * new TranslatableMarkup($text)
    * @endcode
-   * - Using a variable for $string that is user input is a security risk.
-   * - Using a variable for $string that has even guaranteed safe text, for
+   * There are several reasons for this:
+   * - using a variable for $string that is user input is a security risk,
+   * - using a variable for $string 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.)
+   *   picked up by the localization static text processor. (Unless the entire
+   *   string in $text has been processed for translation as one entire literal
+   *   string elsewhere But that strategy is not recommended.)
    *
    * It is especially important never to call new TranslatableMarkup($user_text)
-   * or t($user_text) where $user_text is some text that a user entered - doing
+   * or 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
-   * new TranlsatableMarkup("@name's blog", array('@name' => $account->getDisplayName()));
+   * new TranslatableMarkup("@name's blog", array('@name' => $account->getDisplayName()));
    * @endcode
-   * Basically, you can put variables like @name into your string, and it will
-   * substitute their sanitized values at translation time. (See the
+   * Basically, you can put variables like @name into your string, and sanitized
+   * values 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
@@ -110,7 +112,7 @@ class TranslatableMarkup extends FormattableMarkup {
    * language (e.g., in Spanish, it might be "blog de @name").
    *
    * @param string $string
-   *   A string containing the English string to translate.
+   *   A string containing the English text to translate.
    * @param array $arguments
    *   (optional) An associative array of replacements to make after
    *   translation. Based on the first character of the key, the value is
@@ -120,7 +122,7 @@ class TranslatableMarkup extends FormattableMarkup {
    * @param array $options
    *   (optional) An associative array of additional options, with the following
    *   elements:
-   *   - 'langcode' (defaults to the current language): The language code to
+   *   - 'langcode' (defaults to the current language): A 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.
diff --git a/core/lib/Drupal/Core/StringTranslation/TranslationInterface.php b/core/lib/Drupal/Core/StringTranslation/TranslationInterface.php
index 2407af1..7c2e14a 100644
--- a/core/lib/Drupal/Core/StringTranslation/TranslationInterface.php
+++ b/core/lib/Drupal/Core/StringTranslation/TranslationInterface.php
@@ -25,7 +25,7 @@
    * \Drupal\Core\StringTranslation\TranslatableMarkup object.
    *
    * @param string $string
-   *   A string containing the English string to translate.
+   *   A string containing the English text to translate.
    * @param array $args
    *   (optional) An associative array of replacements to make after
    *   translation. Based on the first character of the key, the value is
@@ -35,13 +35,13 @@
    * @param array $options
    *   (optional) An associative array of additional options, with the following
    *   elements:
-   *   - 'langcode' (defaults to the current language): The language code to
+   *   - 'langcode' (defaults to the current language): A 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.
+   *   An object that, when cast to a string, returns the translated string.
    *
    * @see \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
    * @see \Drupal\Core\StringTranslation\TranslatableMarkup::__construct()
diff --git a/core/lib/Drupal/Core/StringTranslation/TranslationManager.php b/core/lib/Drupal/Core/StringTranslation/TranslationManager.php
index 9d3966b..e9962d6 100644
--- a/core/lib/Drupal/Core/StringTranslation/TranslationManager.php
+++ b/core/lib/Drupal/Core/StringTranslation/TranslationManager.php
@@ -123,7 +123,7 @@ public function translateString(TranslatableMarkup $translated_string) {
    * Translates a string to the current language or to a given language.
    *
    * @param string $string
-   *   A string containing the English string to translate.
+   *   A string containing the English text to translate.
    * @param array $options
    *   An associative array of additional options, with the following elements:
    *   - 'langcode': The language code to translate to a language other than
diff --git a/core/misc/drupal.js b/core/misc/drupal.js
index f1f7d6f..f19fc43 100644
--- a/core/misc/drupal.js
+++ b/core/misc/drupal.js
@@ -362,7 +362,7 @@ if (window.jQuery) {
    * See the documentation of the server-side t() function for further details.
    *
    * @param {string} str
-   *   A string containing the English string to translate.
+   *   A string containing the English text to translate.
    * @param {Object.<string, string>} [args]
    *   An object of replacements pairs to make after translation. Incidences
    *   of any key in this array are replaced with the corresponding value.
diff --git a/core/tests/Drupal/Tests/Core/StringTranslation/TranslationManagerTest.php b/core/tests/Drupal/Tests/Core/StringTranslation/TranslationManagerTest.php
index 305963d..1a99bbf 100644
--- a/core/tests/Drupal/Tests/Core/StringTranslation/TranslationManagerTest.php
+++ b/core/tests/Drupal/Tests/Core/StringTranslation/TranslationManagerTest.php
@@ -66,7 +66,7 @@ public function testFormatPlural($count, $singular, $plural, array $args = array
    * Tests translation using placeholders.
    *
    * @param string $string
-   *   A string containing the English string to translate.
+   *   A string containing the English text to translate.
    * @param array $args
    *   An associative array of replacements to make after translation.
    * @param string $expected_string