Converter Bundle Laravel Package

Getting Started

This package is a Laravel integration that resolves and uses a translation translator contract. The v1.10.1 release is a small but practical compatibility patch: it switches the package’s internal dependency to Symfony\Contracts\Translation\TranslatorInterface, which is the non-deprecated Symfony contract implemented by Laravel’s translator. If you previously hit container resolution or type-hint errors when injecting a translator, start here.

Minimal steps:

1. Install with Composer and let Laravel’s package discovery register the service provider. If the package ships a config file, publish it with php artisan vendor:publish and review the translator/locale bindings.
2. Confirm which translator contract the package binds in its service provider. With v1.10.1, the package should be compatible with Symfony\Contracts\Translation\TranslatorInterface; Laravel’s own Illuminate\Contracts\Translation\Translator extends that Symfony contract in current Laravel versions, so both should resolve through the container.
3. First use case: inject the translator into a service, job, or controller and translate a string:

use Symfony\Contracts\Translation\TranslatorInterface;

public function __construct(private TranslatorInterface $translator) {}

public function handle(): string
{
    return $this->translator->trans('messages.welcome');
}

4. Where to look first: the package README for the supported Laravel/Symfony version matrix, the service provider for the container alias, and any config file for locale/fallback settings.

Implementation Patterns

Prefer constructor injection over the __() helper when you want testability. The helper is convenient in Blade and controllers, but injecting TranslatorInterface makes unit tests straightforward and avoids coupling to global state.

Use the Symfony contract at boundaries, the Laravel contract inside app code where appropriate. If your application code is Laravel-specific, type-hinting Illuminate\Contracts\Translation\Translator is usually clearest. If you are writing reusable package code or listeners that may be shared outside Laravel, type-hint Symfony\Contracts\Translation\TranslatorInterface. v1.10.1 makes the latter safe with this package.

Bind a test double in tests. Because the package now relies on the Symfony contract, you can swap in a mock or a small fake translator:

$this->app->instance(TranslatorInterface::class, new class implements TranslatorInterface {
    public function trans(string $id, array $parameters = [], string $domain = null, string $locale = null): string
    {
        return strtr($id, $parameters);
    }

    public function getCatalogue(string $locale = null): CatalogueInterface { /* ... */ }
    public function getLocales(): array { return ['en']; }
});

Locale-aware workflows. A common integration pattern is a SetLocale middleware that reads the user preference or Accept-Language header, calls App::setLocale($locale), and lets the package’s translator resolve messages in the request lifecycle. Keep locale resolution in one middleware rather than scattering App::setLocale() calls.

Translation domains and JSON keys. If the package exposes domain-aware translation, standardise on either PHP array keys (messages.welcome) or JSON keys (Welcome) per domain. Mixing both makes fallback behaviour hard to debug, especially when the package delegates to Laravel’s translator.

Fallback chains. Configure fallback_locale in config/app.php and verify the package respects it. When adding a new locale, test a missing key to confirm the fallback actually fires rather than returning the raw key.

Gotchas and Tips

• The v1.10.1 fix is specifically about the Symfony contract. If you are on an older version of this package and your container cannot resolve Symfony\Contracts\Translation\TranslatorInterface, upgrade. Do not work around it by type-hinting the deprecated Symfony\Component\Translation\TranslatorInterface; that interface was removed/deprecated across Symfony versions and will break on newer stacks.
• Laravel’s container binding is for translator, not necessarily for the Symfony interface. Laravel binds Illuminate\Contracts\Translation\Translator and the translator singleton. If you type-hint the Symfony contract directly in your own code, verify the package or your own service provider aliases it. A missing alias produces a Target [Symfony\Contracts\Translation\TranslatorInterface] is not instantiable error.
• Config caching hides binding changes. After changing translator-related config or service provider aliases, run php artisan config:clear and php artisan cache:clear. In production, config:cache can mask locale or fallback changes.
• Version constraints matter. Check the package’s composer.json constraints for symfony/translation and illuminate/support. A patch release like v1.10.1 is usually safe, but if you are pinned to an older Symfony major, confirm the new contract exists in your installed version.
• Debugging missing translations. Use php artisan lang:publish if needed, then verify the file path matches the locale and domain. For JSON translations, the file must be lang/{locale}.json (or resources/lang/{locale}.json on older Laravel). A missing file silently returns the key, which can look like a package bug.
• Extension point: custom translator loader. If the package exposes a loader or translator resolver, bind your implementation after the package’s service provider in AppServiceProvider::register() so your binding wins. Laravel resolves in registration order, and later bindings override earlier ones.
• Testing tip. Use $this->app->setLocale('fr') in feature tests and assert on rendered output, not on internal translator calls. This keeps tests resilient to the package switching between Symfony and Laravel contracts in future patch releases.