Issue #2552867 by jhodgdon, Gábor Hojtsy, pjonckiere: Document...

Issue #2552867 by jhodgdon, Gábor Hojtsy, pjonckiere: Document DrupalTranslator::transChoice()'s non-standard formatPlural() usage

core/lib/Drupal/Core/Validation/DrupalTranslator.php

@@ -41,6 +41,17 @@ public function transChoice($id, $number, array $parameters = array(), $domain =
     if (!isset($ids[1])) {
       throw new \InvalidArgumentException(sprintf('The message "%s" cannot be pluralized, because it is missing a plural (e.g. "There is one apple|There are @count apples").', $id));
     }
+
+    // Normally, calls to formatPlural() need to use literal strings, like
+    //   formatPlural($count, '1 item', '@count items')
+    // so that the Drupal project POTX string extractor will correctly
+    // extract the strings for translation and save them in a format that
+    // formatPlural() can work with. However, this is a special case, because
+    // Drupal is supporting a constraint message format from Symfony. So
+    // although $id looks like a variable here, it is actually coming from a
+    // static string in a constraint class that the POTX extractor knows about
+    // and has processed to work with formatPlural(), so this specific call to
+    // formatPlural() will work correctly.
     return \Drupal::translation()->formatPlural($number, $ids[0], $ids[1], $this->processParameters($parameters), $this->getOptions($domain, $locale));
   }