lambdadigamma/laravel-api-language

A simple package for making a Laravel API language header aware.

1.2.0 2026-05-27 13:31 UTC

Requires

• php: ^8.3 || ^8.4
• ext-intl: *
• illuminate/contracts: ^11.0 || ^12.0 || ^13.0
• illuminate/http: ^11.0 || ^12.0 || ^13.0
• illuminate/support: ^11.0 || ^12.0 || ^13.0
• spatie/laravel-package-tools: ^1.16.4 || ^1.93
• symfony/http-foundation: ^7.0 || ^8.0

Requires (Dev)

• nunomaduro/collision: ^8.6.1
• orchestra/testbench: ^9.0 || ^10.1 || ^11.0
• pestphp/pest: ^3.0 || ^4.0
• spatie/laravel-ray: ^1.39.1
• vimeo/psalm: ^6.8.8

MIT

• Lennart Fischer

• middleware
• laravel
• content language
• LambdaDigamma
• laravel-api-language
• accept language

README

Installation

You can install the package via composer:

composer require lambdadigamma/laravel-api-language

You can publish the config file with:

php artisan vendor:publish --provider="Lambdadigamma\LaravelApiLanguage\LaravelApiLanguageServiceProvider" --tag="api-language-config"

This is the contents of the published config file:

return [

    'supported_locales' => ['en'],

    'fallback_locale' => null,

    'use_autoscan_lang_folder' => false,

    'cache' => [
        'supported_locales_key' => 'api-language.supported-locales',
    ],

    'request_attributes' => [
        'accepted_locales' => 'api_language.accepted_locales',
        'excluded_locales' => 'api_language.excluded_locales',
        'resolved_locale' => 'api_language.resolved_locale',
        'result' => 'api_language.result',
    ],

    'prefer_user_locale' => true,

    'user_locale_attribute' => 'locale',

    'automatic_vary_header' => true,

];

Usage

To use the accept language middleware, register it with your application's middleware.

In Laravel 11 and newer, append it to the API middleware group in bootstrap/app.php:

use Illuminate\Foundation\Configuration\Middleware;
use Lambdadigamma\LaravelApiLanguage\Http\Middleware\AcceptLanguageMiddleware;

->withMiddleware(function (Middleware $middleware) {
    $middleware->api(append: [
        AcceptLanguageMiddleware::class,
    ]);
})

In older Laravel applications, register it as a global middleware:

protected $middleware = [
    ...
    \Lambdadigamma\LaravelApiLanguage\Http\Middleware\AcceptLanguageMiddleware::class,
];

Register in a specific middleware group:

protected $middlewareGroups = [
    'api' => [
        ...
        \Lambdadigamma\LaravelApiLanguage\Http\Middleware\AcceptLanguageMiddleware::class,
    ]
];

The middleware stores the full negotiation result on the request. This is useful for APIs that need to pick resource-specific translations instead of only setting Laravel's application locale:

$acceptedLocales = $request->attributes->get('api_language.accepted_locales', []);
$excludedLocales = $request->attributes->get('api_language.excluded_locales', []);
$resolvedLocale = $request->attributes->get('api_language.resolved_locale');

You can also use the negotiator directly:

use Lambdadigamma\LaravelApiLanguage\LanguageNegotiator;

$result = app(LanguageNegotiator::class)->negotiate($request);

$result->acceptedLocales; // ordered positive locales, including positive * and excluding q=0
$result->excludedLocales; // q=0 locales, including *
$result->resolvedLocale;  // best supported application locale
$result->resolvedLocaleIsAcceptable; // false when every supported locale is excluded

Use isAcceptedLocaleExcluded() when checking an explicit positive locale from acceptedLocales; it honors concrete q=0 ranges without letting *;q=0 reject explicitly accepted languages.

AcceptLanguageMiddleware adds Vary: Accept-Language by default. Disable this with automatic_vary_header if another layer owns response cache variation. When prefer_user_locale is enabled for authenticated APIs, make sure those responses are private/auth-aware in your cache layer because the resolved locale can also depend on the current user.

ContentLanguageMiddleware is available for single-locale responses. It will not overwrite an existing Content-Language header.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Lennart Fischer
• All Contributors

License

The MIT License (MIT). Please see License File for more information.