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/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,150 @@
+# TransModifier
+
+The `|trans` modifier translates string values using Symfony Translation component.
+
+## Purpose
+
+The `|trans` modifier enables internationalization by translating string keys into their localized equivalents, supporting multi-language applications with minimal configuration.
+
+## Behavior
+
+The modifier follows the Chain of Responsibility pattern and only processes string values with the `trans` pipe:
+
+- **Non-trans pipes**: Delegates to next modifier without modification
+- **Non-string values**: Delegates to next modifier without modification
+- **String values with `trans` pipe**: Passes through translator and continues chain
+- **Missing translations**: Returns the original key unchanged
+
+## Usage
+
+### Simple Usage (Default BypassTranslator)
+
+```php
+use Respect\StringFormatter\PlaceholderFormatter;
+
+// Works out of the box - no dependencies required
+$formatter = new PlaceholderFormatter(['message' => 'hello']);
+
+echo $formatter->format('{{message|trans}}');
+// Outputs: "hello" (original input returned)
+```
+
+### With Real Translator
+
+```php
+use Respect\StringFormatter\PlaceholderFormatter;
+use Respect\StringFormatter\Modifier\TransModifier;
+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(
+    ['message' => 'greeting'],
+    new TransModifier($nextModifier, $translator) // Inject real translator
+);
+
+echo $formatter->format('{{message|trans}}');
+// Outputs: "Hello World" (translated result)
+```
+
+## Examples
+
+### With BypassTranslator (Default)
+
+| Parameters             | Template               | Output      |
+| ---------------------- | ---------------------- | ----------- |
+| `['msg' => 'hello']`   | `"{{msg|trans}}"` | `"hello"`   |
+| `['msg' => 'welcome']` | `"{{msg|trans}}"` | `"welcome"` |
+| `['msg' => 'unknown']` | `"{{msg|trans}}"` | `"unknown"` |
+
+### With Real Translator
+
+| Parameters              | Template               | Output          |
+| ----------------------- | ---------------------- | --------------- |
+| `['msg' => 'greeting']` | `"{{msg|trans}}"` | `"Hello World"` |
+
+### Mixed with Regular Placeholders
+
+| Parameters                                  | Template                              | Output          |
+| ------------------------------------------- | ------------------------------------- | --------------- |
+| `['name' => 'John', 'greeting' => 'hello']` | `"{{greeting|trans}}, {{name}}"` | `"hello, John"` |
+
+## Common Use Cases
+
+1. **User interface messages** - Internationalize button labels, error messages, notifications
+2. **Email templates** - Send localized emails to international users
+3. **Error presentation** - Show validation errors in user's preferred language
+4. **Report generation** - Generate reports in different languages
+5. **Content management** - Translate article headings, descriptions, UI elements
+
+## Implementation Notes
+
+The `TransModifier` requires a `Symfony\Contracts\Translation\TranslatorInterface` implementation. The modifier:
+
+1. Checks for exact match with `trans` pipe value
+2. Validates input is a string
+3. Calls `translator->trans($value)` without parameters for simplicity
+4. Passes translated result to next modifier in chain
+5. Returns original key if translation not found
+
+## Integration
+
+`TransModifier` is typically used in the middle of the modification chain:
+
+```php
+CustomModifier -> TransModifier -> RawModifier -> StringifyModifier
+```
+
+The modifier processes translations first, then passes the result to subsequent modifiers for consistent formatting across the application.
+
+## Dependencies
+
+**Required:**
+
+- `symfony/translation-contracts`: Provides the `TranslatorInterface` contract
+
+**Optional/Suggested:**
+
+- `symfony/translation`: Implementation of the translation interface
+  - Install with: `composer require symfony/translation`
+  - Required for actual translation functionality
+  - Package is suggested and will be installed when needed
+
+## Default Behavior
+
+The `TransModifier` works out of the box without requiring symfony/translation. By default, it uses a `BypassTranslator` that returns the original input unchanged. This means the modifier is always available and functional.
+
+## Real Translations
+
+To enable actual translations, install symfony/translation and inject it into the constructor:
+
+```php
+use Respect\StringFormatter\Modifier\TransModifier;
+use Symfony\Component\Translation\Translator;
+use Symfony\Component\Translation\Loader\ArrayLoader;
+
+$translator = new Translator('en');
+$translator->addLoader('array', new ArrayLoader());
+$translator->addResource('array', ['hello' => 'Hello World'], 'en');
+
+// Inject into specific TransModifier instance
+$modifier = new TransModifier($nextModifier, $translator);
+```
+
+## Testing
+
+For testing purposes, the `TestingTranslator` implementation is provided:
+
+```php
+use Respect\StringFormatter\Test\Helper\TestingTranslator;
+
+$translator = new TestingTranslator([
+    'hello' => 'Hello World',
+    'welcome' => 'Welcome',
+]);
+```
+
+This provides a lightweight way to test translation behavior without requiring the full Symfony Translation component. The testing implementation is included in the dev dependencies.

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/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
+    }
+}