Issue #3368808: Override Composer Stager's TranslatableFactory to return Drupal's TranslatableMarkup

package_manager/src/TranslatableStringAdapter.php

@@ -14,6 +14,10 @@ use PhpTuf\ComposerStager\API\Translation\Value\TranslationParametersInterface;
  *
  * This class is designed to adapt Drupal's style of string translation so it
  * can be used with the Symfony-inspired architecture used by Composer Stager.
+ *
+ * If this object is cast to a string, it will be translated by Drupal's
+ * translation system. It will ONLY be translated by Composer Stager if the
+ * trans() method is explicitly called.
  */
 final class TranslatableStringAdapter extends TranslatableMarkup implements TranslatableInterface, TranslationParametersInterface {
 
@@ -28,9 +32,14 @@ final class TranslatableStringAdapter extends TranslatableMarkup implements Tran
    * {@inheritdoc}
    */
   public function trans(TranslatorInterface $translator, ?string $locale = NULL): string {
+    // This method is NEVER used by Drupal to translate the underlying string;
+    // it exists to solely so Composer Stager's translation system can
+    // transparently translate Drupal strings using its own architecture.
     return $translator->trans(
       $this->getUntranslatedString(),
       $this,
+      // The 'context' option is the closest analogue to the Symfony-inspired
+      // concept of translation domains.
       $this->getOption('context'),
       $locale ?? $this->getOption('langcode'),
     );