Add TransModifier to support localized template interpolation

Another need we had in Respect\Validation was the ability to translate
parameters into a different language, and I wanted to port that functionality to
this library as well. I’ve ported the `TransModifier` from Validation, allowing
us to bridge the gap between template interpolation and localization.

Instead of reinventing the wheel, I’ve integrated this modifier with
`symfony/translation`. By relying on the TranslatorInterface, we ensure robust
translation ecosystems without being locked into a specific implementation.

Assisted-by: OpenCode (GLM-4.6)
Assisted-by: Gemini 3 (Thinking)

Author: henriquemoody

composer.json

@@ -5,15 +5,20 @@
     "require": {
         "symfony/polyfill-mbstring": "^1.33",
         "php": "^8.5",
-        "respect/stringifier": "^3.0"
+        "respect/stringifier": "^3.0",
+        "symfony/translation-contracts": "^3.6"
+    },
+    "suggest": {
+        "symfony/translation": "For translation support in TransModifier (^6.0|^7.0)"
     },
     "require-dev": {
         "phpunit/phpunit": "^12.5",
         "phpstan/phpstan": "^2.1",
         "phpstan/extension-installer": "^1.4",
         "phpstan/phpstan-deprecation-rules": "^2.0",
         "phpstan/phpstan-phpunit": "^2.0",
-        "respect/coding-standard": "^5.0"
+        "respect/coding-standard": "^5.0",
+        "symfony/translation": "^6.0|^7.0"
     },
     "license": "ISC",
     "autoload": {

docs/modifiers/ListModifier.md

@@ -41,3 +41,7 @@ echo $formatter->format('Choose {{fruits|list:or}}');
 | `['items' => ['a', 'b']]`      | `{{items\|list:or}}`  | `a or b`      |
 | `['items' => ['a', 'b', 'c']]` | `{{items\|list:and}}` | `a, b, and c` |
 | `['items' => ['a', 'b', 'c']]` | `{{items\|list:or}}`  | `a, b, or c`  |
+
+## Known Limitations
+
+This modifier uses the Oxford comma (a comma before the conjunction) for lists with 3+ items. This grammar rule is specific to English and may not work well with other languages.

docs/modifiers/Modifiers.md

@@ -52,6 +52,7 @@ If no modifier is provided, the formatter uses `StringifyModifier` by default.
 - **[ListModifier](ListModifier.md)** - Formats arrays as human-readable lists with conjunctions
 - **[QuoteModifier](QuoteModifier.md)** - Quotes string values using a stringifier quoter
 - **[StringifyModifier](StringifyModifier.md)** - Converts values to strings (default)
+- **[TransModifier](TransModifier.md)** - Translates string values using a Symfony translator
 
 ## Creating Custom Modifiers
 

docs/modifiers/TransModifier.md

@@ -0,0 +1,53 @@
+# TransModifier
+
+The `|trans` modifier translates string values using a `TranslatorInterface` implementation.
+
+## Behavior
+
+- String values with `|trans` pipe are passed through the translator
+- Non-string values delegate to the next modifier
+- Missing translations return the original key unchanged
+
+## Usage
+
+By default, uses a `BypassTranslator` that returns the original input:
+
+```php
+use Respect\StringFormatter\PlaceholderFormatter;
+
+$formatter = new PlaceholderFormatter(['message' => 'hello']);
+
+echo $formatter->format('{{message|trans}}');
+// Output: hello
+```
+
+## With Symfony Translator
+
+Install `symfony/translation` and inject a real translator:
+
+```php
+use Respect\StringFormatter\PlaceholderFormatter;
+use Respect\StringFormatter\Modifiers\TransModifier;
+use Respect\StringFormatter\Modifiers\StringifyModifier;
+use Symfony\Component\Translation\Translator;
+use Symfony\Component\Translation\Loader\ArrayLoader;
+
+$translator = new Translator('en');
+$translator->addLoader('array', new ArrayLoader());
+$translator->addResource('array', ['greeting' => 'Hello World'], 'en');
+
+$formatter = new PlaceholderFormatter(
+    ['key' => 'greeting'],
+    new TransModifier(new StringifyModifier(), $translator),
+);
+
+echo $formatter->format('{{key|trans}}');
+// Output: Hello World
+```
+
+## Examples
+
+| Parameters              | Template         | Output        |
+| ----------------------- | ---------------- | ------------- |
+| `['msg' => 'hello']`    | `{{msg\|trans}}` | `hello`       |
+| `['key' => 'greeting']` | `{{key\|trans}}` | `Hello World` |

src/BypassTranslator.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Respect\StringFormatter;
+
+use Symfony\Contracts\Translation\TranslatorInterface;
+
+/**
+ * Bypass translator that always returns the original input.
+ *
+ * This implementation works regardless of whether symfony/translation
+ * is installed, providing a fallback.
+ */
+final class BypassTranslator implements TranslatorInterface
+{
+    /** @param array<string, mixed> $parameters */
+    public function trans(
+        string $id,
+        array $parameters = [],
+        string|null $domain = null,
+        string|null $locale = null,
+    ): string {
+        return $id;
+    }
+
+    public function getLocale(): string
+    {
+        return 'en';
+    }
+}

src/Modifiers/ListModifier.php

@@ -4,7 +4,9 @@
 
 namespace Respect\StringFormatter\Modifiers;
 
+use Respect\StringFormatter\BypassTranslator;
 use Respect\StringFormatter\Modifier;
+use Symfony\Contracts\Translation\TranslatorInterface;
 
 use function array_map;
 use function array_pop;
@@ -19,6 +21,7 @@
 
     public function __construct(
         private Modifier $nextModifier,
+        private TranslatorInterface $translator = new BypassTranslator(),
     ) {
     }
 
@@ -34,17 +37,17 @@ public function modify(mixed $value, string|null $pipe): string
 
         $modifiedValues = array_map(fn($item) => $this->nextModifier->modify($item, null), $value);
 
-        $glue = match ($pipe) {
+        $conjunction = $this->translator->trans(match ($pipe) {
             'list:and', 'list' => 'and',
             'list:or' => 'or',
-        };
+        });
 
         if (count($value) < 3) {
-            return implode(' ' . $glue . ' ', $modifiedValues);
+            return implode(' ' . $conjunction . ' ', $modifiedValues);
         }
 
         $last = array_pop($modifiedValues);
 
-        return implode(', ', $modifiedValues) . ', ' . $glue . ' ' . $last;
+        return implode(', ', $modifiedValues) . ', ' . $conjunction . ' ' . $last;
     }
 }

src/Modifiers/TransModifier.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Respect\StringFormatter\Modifiers;
+
+use Respect\StringFormatter\BypassTranslator;
+use Respect\StringFormatter\Modifier;
+use Symfony\Contracts\Translation\TranslatorInterface;
+
+use function is_string;
+
+final readonly class TransModifier implements Modifier
+{
+    public function __construct(
+        private Modifier $nextModifier,
+        private TranslatorInterface $translator = new BypassTranslator(),
+    ) {
+    }
+
+    public function modify(mixed $value, string|null $pipe): string
+    {
+        if ($pipe !== 'trans') {
+            return $this->nextModifier->modify($value, $pipe);
+        }
+
+        if (!is_string($value)) {
+            return $this->nextModifier->modify($value, null);
+        }
+
+        return $this->translator->trans($value);
+    }
+}

src/PlaceholderFormatter.php

@@ -7,6 +7,7 @@
 use Respect\StringFormatter\Modifiers\ListModifier;
 use Respect\StringFormatter\Modifiers\QuoteModifier;
 use Respect\StringFormatter\Modifiers\StringifyModifier;
+use Respect\StringFormatter\Modifiers\TransModifier;
 
 use function array_key_exists;
 use function is_string;
@@ -17,7 +18,7 @@
     /** @param array<string, mixed> $parameters */
     public function __construct(
         private array $parameters,
-        private Modifier $modifier = new QuoteModifier(new ListModifier(new StringifyModifier())),
+        private Modifier $modifier = new TransModifier(new QuoteModifier(new ListModifier(new StringifyModifier()))),
     ) {
     }
 

tests/Helper/TestingTranslator.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Respect\StringFormatter\Test\Helper;
+
+use Symfony\Contracts\Translation\LocaleAwareInterface;
+use Symfony\Contracts\Translation\TranslatorInterface;
+
+/**
+ * Dumb test implementation of TranslatorInterface
+ *
+ * This implementation simply replaces input strings with mapped replacements
+ * and doesn't implement any actual translation logic.
+ * Used only to test that the TransModifier is using the translator correctly.
+ */
+final class TestingTranslator implements TranslatorInterface, LocaleAwareInterface
+{
+    /** @param array<string, string> $translations */
+    public function __construct(
+        private array $translations = [],
+    ) {
+    }
+
+    /** @param array<string, mixed> $parameters */
+    public function trans(
+        string $id,
+        array $parameters = [],
+        string|null $domain = null,
+        string|null $locale = null,
+    ): string {
+        return $this->translations[$id] ?? $id;
+    }
+
+    public function getLocale(): string
+    {
+        return 'en';
+    }
+
+    public function setLocale(string $locale): void
+    {
+        // Dummy implementation - not needed for testing
+    }
+}

tests/Unit/BypassTranslatorTest.php

@@ -0,0 +1,102 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Respect\StringFormatter\Test\Unit;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+use Respect\StringFormatter\BypassTranslator;
+
+#[CoversClass(BypassTranslator::class)]
+final class BypassTranslatorTest extends TestCase
+{
+    private BypassTranslator $translator;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->translator = new BypassTranslator();
+    }
+
+    #[Test]
+    public function itShouldReturnOriginalIdForTranslation(): void
+    {
+        $id = 'some.translation.key';
+        $parameters = ['param1' => 'value1'];
+        $domain = 'messages';
+        $locale = 'en';
+
+        $result = $this->translator->trans($id, $parameters, $domain, $locale);
+
+        self::assertSame($id, $result);
+    }
+
+    #[Test]
+    public function itShouldReturnOriginalIdForTranslationWithMinimalParameters(): void
+    {
+        $id = 'simple.key';
+
+        $result = $this->translator->trans($id);
+
+        self::assertSame($id, $result);
+    }
+
+    #[Test]
+    public function itShouldReturnOriginalIdForTranslationWithEmptyParameters(): void
+    {
+        $id = 'key.with.no.params';
+
+        $result = $this->translator->trans($id, []);
+
+        self::assertSame($id, $result);
+    }
+
+    #[Test]
+    public function itShouldReturnOriginalIdForTranslationWithNullDomainAndLocale(): void
+    {
+        $id = 'key.with.nulls';
+
+        $result = $this->translator->trans($id, ['param' => 'value'], null, null);
+
+        self::assertSame($id, $result);
+    }
+
+    #[Test]
+    public function itShouldAlwaysReturnEnglishAsDefaultLocale(): void
+    {
+        $locale = $this->translator->getLocale();
+
+        self::assertSame('en', $locale);
+    }
+
+    #[Test]
+    public function itShouldHandleEmptyStringTranslation(): void
+    {
+        $result = $this->translator->trans('');
+
+        self::assertSame('', $result);
+    }
+
+    #[Test]
+    public function itShouldHandleComplexTranslationKeyId(): void
+    {
+        $complexId = 'nested.deep.very.complex.translation.key.with.dots';
+
+        $result = $this->translator->trans($complexId, ['param' => 'value'], 'domain', 'fr_FR');
+
+        self::assertSame($complexId, $result);
+    }
+
+    #[Test]
+    public function itShouldHandleSpecialCharactersInTranslationKey(): void
+    {
+        $specialId = 'key.with-special_chars@123#$%';
+
+        $result = $this->translator->trans($specialId);
+
+        self::assertSame($specialId, $result);
+    }
+}