Localization is an important feature in modern web applications, especially when your users belong to different regions and speak different languages. When developing APIs with Laravel, it is often necessary to return responses in multiple languages depending on the user’s preference. Laravel provides a powerful localization system that makes it easy to translate application content.
One of the best ways to implement REST API localization in Laravel is by using middleware. Middleware allows you to intercept incoming API requests, check for language preferences, and dynamically set the application language before the request reaches the controller.
In this guide, we will learn how to implement Laravel API localization using middleware, allowing API responses to be translated into multiple international languages.
Why API Localization is Important
API localization helps applications serve users from different countries more effectively. When your API returns responses in the user’s preferred language, it improves usability and enhances the overall user experience.
For example, an application serving users in the United States, France, and Pakistan may need to return responses in English, French, and Urdu. By implementing localization at the API level, you can ensure all messages, validation errors, and responses are translated automatically.
Laravel makes this process simple with its built-in language files and localization helpers.
Step 1: Creating Language Middleware
The first step in implementing localization for Laravel APIs is creating a custom middleware that will detect the language from the API request.
In this example, we will create a middleware called ApiLocalization.
Run the following Artisan command in your Laravel project:
php artisan make:middleware ApiLocalization
After running the command, Laravel will generate a new middleware file in the following directory:
app/Http/Middleware/ApiLocalization.php
This middleware will be responsible for reading the language preference from the request header and setting the application locale accordingly.
Step 2: Update the ApiLocalization Middleware
Next, open the newly created middleware file and update the logic so it checks for a custom request header named X-localization.
This header will allow API clients to specify the language they want in the response.
Example :
public function handle($request, Closure $next)
{
$local = ($request->hasHeader('X-localization'))
? $request->header('X-localization')
: 'en';
app()->setLocale($local);
return $next($request);
}
How This Code Works
The middleware performs three simple tasks:
- It checks whether the API request contains the X-localization header.
- If the header exists, it retrieves the language code from the request.
- If the header does not exist, it defaults to English (en).
After determining the language, the middleware sets the application locale using:
app()->setLocale($local);
This ensures that Laravel uses the selected language when returning translated messages.
Step 3: Register the Middleware
Once the middleware is created and configured, the next step is to register it so that Laravel can use it for API requests.
Open the following file:
app/Http/Kernel.php
Inside the $routeMiddleware array, add the new middleware:
'api.localization' => \App\Http\Middleware\ApiLocalization::class,
Now the middleware is available for use in routes.
Step 4: Apply Middleware to API Routes
After registering the middleware, you need to apply it to your API routes.
Open the routes/api.php file and wrap your routes with the localization middleware.
Example:
Route::middleware(['api.localization'])->group(function () {
Route::get('/message', function () {
return response()->json([
'message' => __('messages.welcome')
]);
});
});
Now every request to this route will first pass through the ApiLocalization middleware, which sets the language before the response is generated.
Step 5: Create Language Files
Laravel uses language files to store translations. These files are located inside the resources/lang directory.
Create language folders like:
resources/lang/en/messages.php
resources/lang/fr/messages.php
resources/lang/ur/messages.php
Example English translation:
return [
'welcome' => 'Welcome to our API'
];
Example French translation:
return [
'welcome' => 'Bienvenue dans notre API'
];
Example Urdu translation:
return [
'welcome' => 'ہماری API میں خوش آمدید'
];
Now Laravel will automatically return the translated message based on the selected locale.
Conclusion
Implementing REST API localization in Laravel using middleware is a simple and effective approach for supporting multiple languages. By creating a custom middleware, checking for a language header, and setting the application locale dynamically, you can easily translate all API responses.
Laravel’s powerful localization system combined with middleware allows developers to build globally accessible APIs that adapt to users from different countries and language backgrounds.
By following the steps outlined in this guide—creating middleware, registering it, applying it to routes, and adding translation files—you can quickly enable multi-language API responses in Laravel applications.
This approach ensures your Laravel APIs remain scalable, maintainable, and user-friendly for a global audience.
