- How do I install and register laravel-accept-language-middleware?
- Install it with Composer using orkhanahmadov/laravel-accept-language-middleware, then register the middleware either globally in the HTTP kernel or on a specific route group where locale negotiation should apply. It works without any configuration out of the box, but you can publish the config to declare the supported locale list it negotiates against. Verify with a request test that sends an Accept-Language header and asserts the resulting application locale.
- Which Laravel and PHP versions does this package support?
- The public changelog does not spell out a clear version matrix for the 3.x line, so check the composer.json constraints in the repository before adopting it. Because the middleware only reads a request header and calls App::setLocale, the framework surface it touches is small and stable across recent Laravel releases. Pin the version and confirm it against your runtime in CI rather than assuming compatibility.
- How does the middleware handle an Accept-Language value that matches none of my configured locales?
- It negotiates the header against your supported locale list and falls back to the application default when nothing matches instead of throwing an error. Be aware that release 3.0.1 fixed a bug where the wildcard * was treated as a literal locale code. Wildcards and weighted values such as en;q=0.9 arrive routinely from crawlers and privacy browsers, so cover those cases in your own tests.
- Does it normalize region variants like pt-BR versus pt_BR and letter casing?
- There is no documented guarantee that region separators or case are normalized before matching, and the wildcard fix shipped in a 3.x release suggests the edge-case test matrix is thin. Test your exact version with pt-BR, pt_BR, EN and malformed headers before depending on the behavior in production. If normalization is missing, standardize the codes in your own supported-locale configuration or wrap the middleware.
- Do I need to send a Vary: Accept-Language header when caching responses?
- Yes. Any response negotiated from a request header must emit Vary: Accept-Language at your CDN or reverse proxy, otherwise one visitor's cached language is served to everyone. This is the highest-severity failure mode for header-based negotiation and it is entirely outside the package's control. If you also use localized URLs, make sure locale is part of your cache key.
- Does the middleware apply locale to queued jobs, console commands and outbound mail?
- No. It only runs during the HTTP request lifecycle, so queued jobs, Artisan commands, scheduled tasks and queued mail will not inherit the negotiated locale. Capture the resolved locale when you dispatch and restore it with App::setLocale inside the job if the output is localized. This is a general Laravel concern that no request middleware can solve for you.
- Can I use it together with mcamara/laravel-localization or another localization package?
- You can, but only one component should own locale resolution. If another package already negotiates and sets the locale, you end up with two components writing the same global state, and the winner depends on middleware ordering. Document the precedence chain explicitly, for example route segment, then session or user preference, then Accept-Language, then the app fallback.
- Is the middleware Octane-safe, and does it persist the locale to the session?
- Locale is applied through the application's locale setter, so under Octane make sure nothing else holds locale in static or container state that leaks between requests. Whether the package writes locale into the session is worth confirming in the source, because a persisted locale changes behavior for multi-tab users and affects your precedence rules. A good check is an Octane test that sends two different Accept-Language headers on consecutive requests.
- When should I build a custom locale resolver instead of using this package?
- Use the package when header-based negotiation alone is enough, for example to ship a cheap multilingual experiment and measure demand before committing translation budget. Build a custom resolver if you need geo-IP, user-profile or account-level locale, or a strict precedence chain spanning routes, sessions and stored preferences. The middleware can still be one stage of that chain, but it should not be the whole strategy.
- Is this package well maintained, and what are the risks of depending on it?
- Adoption is low (around 16 stars) and it is effectively a single-maintainer project, so vendor risk is real. The MIT license and tiny surface area mean you can fork or vendor the code in a day if maintenance stalls. The bigger operational risk is silent failures, because a regression here serves the wrong language rather than throwing an error, so add request tests and monitor locale output.