Translation Contracts Laravel Package

Getting Started

Start by installing the package via Composer:

composer require symfony/translation-contracts

This package provides only interfaces — it has no concrete implementation. Your first use case will likely be integrating translation into your own framework or library (e.g., writing a custom translator that implements Symfony\Contracts\Translation\TranslatorInterface). Read the interfaces in src/Translation/ — especially TranslatorInterface, TranslatableInterface, and MessageCatalogueInterface. These define the contract for translating messages, handling parameters, pluralization, and locale switching.

Implementation Patterns

• Custom Translator Implementation: Implement TranslatorInterface to build a translator for your stack (e.g., using PO files, JSON, or a database). Use TranslatorTrait to reduce boilerplate.
• Message Objects: Return or pass TranslatableInterface objects (e.g., Symfony\Contracts\Translation\TranslatableMessage) instead of raw strings to defer translation and preserve context.
• Declarative UIs: Use translatable messages in templates or API responses (e.g., in Laravel with Blade macros or in Livewire components) to decouple translation logic from rendering.
• Catalogue Management: Implement MessageCatalogueInterface to manage locales and message domains — useful when building i18n-aware CLI tools or headless CMS backends.
• Dependency Injection: Inject TranslatorInterface wherever translation is needed, promoting testability and testability-friendly design (e.g., mock in unit tests).

Gotchas and Tips

• ❗ No implementation included: This package only defines contracts. You’ll need a concrete translator (e.g., symfony/translation package) to actually translate messages in production.
• ❗ Parameter syntax varies: The trans() method uses :placeholder syntax by default — but real-world implementations (like symfony/translation) support ICU MessageFormat ({count, plural, =0{...}}) — ensure your translator supports the format you expect.
• ⚠️ Missing pluralization helpers: The contract defines trans() but not helper methods like transChoice(). Implementations often add their own — don’t rely on them unless using symfony/translation.
• 🔍 Debug tip: When mocking TranslatorInterface, set strict expectations on locale and domain — mismatches here are common sources of silent translation failures.
• 🛠️ Extend with traits: TranslatorTrait offers fallback and parameter substitution logic — reuse it when building lightweight translators.
• 🌐 Locale awareness: Always set the translator locale before calling trans() — the contract assumes your implementation respects locale changes (e.g., setLocale() or via context-aware resolvers).