- How does avris/localisator detect the user's locale in a Laravel app?
- Localisator checks multiple sources in order: URL parameters, HTTP headers (e.g., `Accept-Language`), session/cookie storage, and finally user preferences. You configure the priority via the `LocalisatorServiceProvider` in `config/localisator.php`. It integrates with Laravel’s native `app()->setLocale()` for persistence.
- Can I use this package with Laravel 10+ without conflicts?
- Yes, Localisator is designed for Laravel 9+ and explicitly supports Laravel 10. It leverages Laravel’s service container and middleware system without overriding core functionality. Always check the package’s `composer.json` for the latest version compatibility.
- What’s the difference between YAML and PHP attributes for translations?
- YAML files (e.g., `resources/lang/en/messages.yml`) are ideal for large translation sets and external tooling (like Crowdin). PHP attributes (`#[Localizable]`) are lightweight for small, inline translations in models or controllers. Both can coexist, with YAML taking precedence in fallback chains.
- How do I force a locale switch in a controller or API route?
- Use the `Localisator::setLocale('fr')` helper or inject the `Localisator` facade. For middleware-based switching, extend `LocalisatorMiddleware` and bind it to specific routes. The locale persists across requests via session or cookie, depending on your config.
- Does this package work with Laravel’s built-in translation system (e.g., `trans()`)?
- Localisator is a drop-in alternative but doesn’t replace `trans()`. It provides `@localize` Blade directives and `localize()` helpers for cleaner syntax. You can migrate incrementally—start with YAML files and replace `trans()` calls where needed. Both systems can read the same `resources/lang` directory.
- What’s the performance impact of using YAML for translations?
- YAML parsing adds minimal overhead if translations are cached (Laravel’s `FileLoader` caches by default). For high-traffic apps, preload translations in a service provider or use JSON instead. Benchmark with your translation volume—Localisator avoids runtime parsing for static keys.
- How do I handle missing translations or fallback locales?
- Configure fallbacks in `config/localisator.php` (e.g., `['en', 'fr']`). Localisator throws a `MissingTranslationException` if no fallback exists; catch it in a global exception handler or use `localize()->fallback('default')` for dynamic handling. Test edge cases with nested keys.
- Can I use this for dynamic content (e.g., user-generated translations)?
- Yes, Localisator supports custom translation sources via the `TranslationSource` interface. Override `getTranslations()` to fetch from a database, API, or cache. Example: `Localisator::addSource(new DatabaseTranslationSource())`. Works alongside YAML/attributes.
- What’s the best way to test locale switching in CI?
- Mock the `Request` object in PHPUnit to simulate locale sources (e.g., `$request->headers->set('Accept-Language', 'es')`). Test middleware with `LocalisatorTestCase` or override `LocalisatorServiceProvider` in tests. Verify session/cookie persistence with `HttpTestCase` and `actingAs()`.
- Are there alternatives to Localisator for Laravel localization?
- For simpler needs, use Laravel’s native `trans()` with JSON/YAML files. For advanced features, consider `spatie/laravel-translatable` (for Eloquent models) or `mccool/laravel-auto-presenter` (for dynamic content). Localisator stands out for its YAML-first approach and middleware integration, ideal for apps needing runtime locale switching.