Symfony Translation Contracts

Symfony Translation Contracts defines a small, dependency-free translation abstraction extracted from Symfony’s Translation component. TranslatorInterface::trans() supports rich ICU-style pluralization (interval and indexed plural forms, e.g. {0} no apples|{1} one apple|]1,Inf] %count% apples) alongside message parameters, domains, and locales, while LocaleAwareInterface and TranslatableInterface round out locale-getting/setting and lazily-translatable value contracts.

A bundled TranslatorTrait gives any class a working, dependency-light implementation of the interface (falling back to PHP’s Locale extension when available), so packages can offer translation support without requiring the full symfony/translation component as a hard dependency.

What You Get

• TranslatorInterface with ICU-style interval and indexed pluralization syntax built into trans()
• LocaleAwareInterface for locale get/set contracts independent of the translator itself
• TranslatableInterface for values that defer translation until actually rendered
• TranslatorTrait, a ready-made pluralization-aware implementation any class can adopt directly

Common Use Cases

• Library authors who want to accept translated strings/messages without requiring symfony/translation as a hard dependency
• Packages implementing a minimal translator via TranslatorTrait instead of writing pluralization logic from scratch
• Building lazily-translatable value objects (TranslatableInterface) that resolve their locale only when the value is actually output

Under The Hood

Architecture — TranslatorTrait::trans() implements the documented pluralization grammar directly: it parses pipe-separated message segments, matches interval notation ({0}, ]1,Inf]) or indexed/labeled forms (one:, more:) against the %count% parameter, and falls back to standard strtr()-based parameter substitution once the correct segment is selected. getLocale() in the trait defers to PHP’s built-in \Locale::getDefault() when the intl extension is present, otherwise defaulting to 'en'.

Tech Stack — PHP 8.1+, PSR-4 autoloaded under Symfony\Contracts\Translation. Zero runtime dependencies — even TranslatorTrait’s reference to Symfony\Component\Translation\Exception\InvalidArgumentException is satisfied only if the consuming package also has that component installed, since the trait’s own contract doesn’t require it.

Code Quality — Ships Test/TranslatorTest.php, an abstract PHPUnit test case implementations can extend to verify pluralization correctness across dozens of interval/indexed cases — the same compliance-suite pattern used by the sibling http-client-contracts package.

API Design — A single trans(string $id, array $parameters = [], ?string $domain = null, ?string $locale = null): string method covers the entire translation surface; the pluralization syntax is embedded in the message string itself rather than requiring separate method calls, keeping the interface small while remaining expressive enough for ICU-style plural rules.