Add TransModifier ported from Respect\Validation

Implement translation support using symfony/translation with
TranslatorInterface dependency injection. Supports simple 'trans'
pipe modifier for string translation following established
modifier patterns.

- Create TransModifier implementing Modifier interface
- Add TestingTranslator for isolated test dependencies
- Follow Chain of Responsibility pattern with proper delegation
- Support symfony/translation-contracts for interface compliance
- Maintain PSR-12 compliance and comprehensive test coverage

Co-authored-by: AI Assistant <ai@example.com>

Author: henriquemoody

AGENTS.md

@@ -34,7 +34,7 @@ All formatters must implement the `Respect\StringFormatter\Formatter` interface.
 When creating new modifiers:
 
 1. **Follow Chain of Responsibility pattern**: Check pipe value and delegate to next modifier
-2. **Use template structure**: Similar to `src/Modifier/QuoteModifier.php` 
+2. **Use template structure**: Similar to `src/Modifier/QuoteModifier.php`
 3. **Test with TestingModifier**: Located in `tests/Helper/TestingModifier.php`
 4. **Handle type checking**: Always check input types before processing
 5. **Return string values**: Modifiers must return strings

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

@@ -33,12 +33,13 @@ Modifiers form a chain where each modifier can:
 The default modifier chain is:
 
 ```
-RawModifier -> ListModifier -> QuoteModifier -> StringifyModifier
+RawModifier -> ListModifier -> TransModifier -> QuoteModifier -> StringifyModifier
 ```
 
 - `StringifyModifier` is always the last modifier, using the stringifier to convert values to strings
 - `RawModifier` processes scalar values without stringifier formatting
 - `ListModifier` formats arrays as human-readable lists with "and" or "or" conjunctions
+- `TransModifier` translates string values using a Symfony translator
 - `QuoteModifier` quotes string values using the stringifier quoter
 
 ## Syntax Rules
@@ -74,6 +75,7 @@ For non-scalar values with `|raw`, the modifier falls back to the next modifier
 - **[StringifyModifier](StringifyModifier.md)** - Default modifier that uses stringifier for all values
 - **[ListModifier](ListModifier.md)** - Formats arrays as human-readable lists with conjunctions
 - **[QuoteModifier](QuoteModifier.md)** - Quotes string values using a stringifier quoter
+- **[TransModifier](TransModifier.md)** - Translates string values using a Symfony translator
 
 ## Creating Custom Modifiers
 
@@ -95,4 +97,4 @@ $formatter = new PlaceholderFormatter(
 );
 ```
 
-If no modifier is provided, the formatter uses a default `RawModifier` with `ListModifier`, `QuoteModifier` and `StringifyModifier`.
+If no modifier is provided, the formatter uses a default `RawModifier` with `ListModifier`, `TransModifier`, `QuoteModifier` and `StringifyModifier`.

docs/modifiers/TransModifier.md

@@ -0,0 +1,148 @@
+# 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($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/Modifier/BypassTranslator.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Respect\StringFormatter\Modifier;
+
+use Symfony\Contracts\Translation\LocaleAwareInterface;
+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 for the TransModifier.
+ */
+final class BypassTranslator implements TranslatorInterface, LocaleAwareInterface
+{
+    public function trans(string $id, array $parameters = [], string|null $domain = null, string|null $locale = null): string
+    {
+        return $id;
+    }
+
+    public function getLocale(): string
+    {
+        return 'en';
+    }
+
+    public function setLocale(string $locale): void
+    {
+        // No-op for bypass translator
+    }
+}

src/Modifier/TransModifier.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Respect\StringFormatter\Modifier;
+
+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' || !is_string($value)) {
+            return $this->nextModifier->modify($value, $pipe);
+        }
+
+        $translated = $this->translator->trans($value);
+
+        return $this->nextModifier->modify($translated, null);
+    }
+}

tests/Helper/TestingTranslator.php

@@ -0,0 +1,40 @@
+<?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> $replacements */
+    public function __construct(
+        private array $replacements,
+    ) {
+    }
+
+    /** @param array<string, mixed> $parameters */
+    public function trans(string $id, array $parameters = [], string|null $domain = null, string|null $locale = null): string
+    {
+        return $this->replacements[$id] ?? $id;
+    }
+
+    public function getLocale(): string
+    {
+        return 'en';
+    }
+
+    public function setLocale(string $locale): void
+    {
+        // Dummy implementation - not needed for testing
+    }
+}