--- a/core/lib/Drupal/Core/Language/language.api.php
+++ b/core/lib/Drupal/Core/Language/language.api.php
@@ -28,10 +28,10 @@
  * - UI text is always put into code and related files in English.
  * - Any time UI text is displayed using PHP code, it should be passed through
  *   either the global t() function or a t() method on the class. If it
- *   involves plurals, it should be passed through either the global
- *   formatPlural() function or a formatPlural() method on the class. Use
- *   \Drupal\Core\StringTranslation\StringTranslationTrait to get these methods
- *   into a class.
+ *   involves plurals, it should be passed through either
+ *   PluralTranslatableMarkup::createFromTranslatedString(), in a global scope,
+ *   or a formatPlural() method in the class
+ *   \Drupal\Core\StringTranslation\StringTranslationTrait.
  * - Dates displayed in the UI should be passed through the 'date' service
  *   class's format() method. Again see the Services topic; the method to
  *   call is \Drupal\Core\Datetime\Date::format().