mcamara/laravel-localization

Instead of using a static config file, you can use a ConfigServiceProvider to dynamically set the laravellocalization configuration settings. This is useful for overriding default settings or setting them based on application logic.

Common keys include:

• laravellocalization.supportedLocales: An array defining supported languages with their name, script, and native names.
• laravellocalization.useAcceptLanguageHeader: Boolean to determine if the Accept-Language header should be used.
• laravellocalization.hideDefaultLocaleInURL: Boolean to determine if the default locale should be hidden from the URL.

<?php namespace App\Providers;

use Illuminate\
Support\ServiceProvider;

class ConfigServiceProvider extends ServiceProvider {
	public function register()
	{
		config([
			'laravellocalization.supportedLocales' => [
				'ace' => array( 'name' => 'Achinese', 'script' => 'Latn', 'native' => 'Aceh' ),
				'ca'  => array( 'name' => 'Catalan', 'script' => 'Latn', 'native' => 'català' ),
				'en'  => array( 'name' => 'English', 'script' => 'Latn', 'native' => 'English' ),
			],

			'laravellocalization.useAcceptLanguageHeader' => true,

			'laravellocalization.hideDefaultLocaleInURL' => true
		]);
	}
}

Because the package detects the active route during the application bootstrap, running tests can result in 404 errors because the route cannot be determined. To fix this, manually define the locale prefix in your TestCase by setting the environment variable LaravelLocalization::ENV_ROUTE_KEY and refreshing the application.

use Illuminateoundation\Testing\TestCase as BaseTestCase;
use Mcamara\LaravelLocalization\LaravelLocalization;

abstract class TestCase extends BaseTestCase
{
    protected function refreshApplicationWithLocale(string $locale): void
    {
        self::tearDown();
        putenv(LaravelLocalization::ENV_ROUTE_KEY . '=' . $locale);
        self::setUp();
    }

    protected function tearDown(): void
    {
        putenv(LaravelLocalization::ENV_ROUTE_KEY);
        parent::tearDown();
    }
}

final class HomeControllerTest extends TestCase
{
    public function it_can_visit_the_home_page()
    {
        $this->refreshApplicationWithLocale('en');

        $response = $this->get('/en');

        $response->assertStatus(200);
    }
}

To support translated slugs in URLs (e.g., /en/article/important-change vs /es/articulo/cambio-importante), your model must implement the \Mcamara\LaravelLocalization\Interfaces\LocalizedUrlRoutable interface.

1. Implement getLocalizedRouteKey($locale): This method must return the translated slug for the given locale.
2. Implement resolveRouteBinding($slug): Overwrite this method to find the model instance using the translated slug.

Example Implementation:

use Mcamara\
LaravelLocalization\\Interfaces\\LocalizedUrlRoutable;

class Article extends Model implements LocalizedUrlRoutable
{
    public function getLocalizedRouteKey($locale)
    {
        // Return the slug for the specific locale
        return $this->slugs()->where('locale', $locale)->first()->slug;
    }

    public function resolveRouteBinding($slug)
    {
        return static::findByLocalizedSlug($slug)->first() ?? abort(404);
    }
}

You can translate route segments (e.g., /en/about and /es/acerca) by following these steps:

1. Ensure the localize middleware is applied to your route group.
2. Create a routes.php file in resources/lang/**/ (or lang/**/ for Laravel 9+) for each language. This file should return an array mapping the internal route key to the translated segment.
3. Use LaravelLocalization::transRoute() within your routes/web.php to define the routes.

Example routes.php (Spanish):

return [
    "about"    =>  "acerca",
    "article"  =>  "articulo/{article}",
];

Example Route Definition:

Route::group(['prefix' => LaravelLocalization::setLocale(), 'middleware' => ['localize']], function () {
    Route::get(LaravelLocalization::transRoute('routes.about'), function () {
        return view('about');
    });
});

<?php
// resources/lang/es/routes.php
return [
    "about"    =>  "acerca",
    "article"  =>  "articulo/{article}",
];

You must register the package middleware to enable routing and redirection features.

For Laravel 11+ (bootstrap/app.php):

return Application::configure(basePath: dirname(__DIR__))
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->alias([
            'localize'                => \Mcamara\LaravelLocalization\Middleware\LaravelLocalizationRoutes::class,
            'localizationRedirect'    => \Mcamara\LaravelLocalization\Middleware\LaravelLocalizationRedirectFilter::class,
            'localeSessionRedirect'   => \Mcamara\LaravelLocalization\Middleware\LocaleSessionRedirect::class,
            'localeCookieRedirect'    => \Mcamara\LaravelLocalization\Middleware\LocaleCookieRedirect::class,
            'localeViewPath'          => \Mcamara\LaravelLocalization\Middleware\LaravelLocalizationViewPath::class
        ]);
    });

For Laravel 10 and below (app/Http/Kernel.php):

protected $middlewareAliases = [
    'localize'                => \Mcamara\LaravelLocalization\Middleware\LaravelLocalizationRoutes::class,
    'localizationRedirect'    => \Mcamara\LaravelLocalization\Middleware\LaravelLocalizationRedirectFilter::class,
    'localeSessionRedirect'   => \Mcamara\LaravelLocalization\Middleware\LocaleSessionRedirect::class,
    'localeCookieRedirect'    => \Mcamara\LaravelLocalization\Middleware\LocaleCookieRedirect::class,
    'localeViewPath'          => \Mcamara\LaravelLocalization\Middleware\LaravelLocalizationViewPath::class
];

// Example for Laravel 11
return Application::configure(basePath: dirname(__DIR__))
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->alias([
            'localize'                => \Mcamara\LaravelLocalization\Middleware\LaravelLocalizationRoutes::class,
            'localizationRedirect'    => \Mcamara\LaravelLocalization\Middleware\LaravelLocalizationRedirectFilter::class,
            'localeSessionRedirect'   => \Mcamara\LaravelLocalization\Middleware\LocaleSessionRedirect::class,
            'localeCookieRedirect'    => \Mcamara\LaravelLocalization\Middleware\LocaleCookieRedirect::class,
            'localeViewPath'          => \Mcamara\LaravelLocalization\Middleware\LaravelLocalizationViewPath::class,
        ]);
    });

By default, this package is incompatible with Laravel's standard route caching (php artisan route:cache). To enable caching for localized routes, you must use the LoadsTranslatedCachedRoutes trait.

For Laravel 11 and newer

Add the trait to your AppServiceProvider and register the routes in the boot method:

use Mcamara\LaravelLocalization\Traits\LoadsTranslatedCachedRoutes;

class AppServiceProvider extends ServiceProvider
{
    use LoadsTranslatedCachedRoutes;

    public function boot(): void
    {
        RouteServiceProvider::loadCachedRoutesUsing(fn () => $this->loadCachedRoutes());
    }
}

For versions before Laravel 11

Add the trait to your RouteServiceProvider:

use Mcamara\LaravelLocalization\Traits\LoadsTranslatedCachedRoutes;

class RouteServiceProvider extends ServiceProvider
{
    use LoadsTranslatedCachedRoutes;
}

Commands

• Cache routes: php artisan route:trans:cache
• Clear cache: php artisan route:trans:clear
• List routes for a locale: php artisan route:trans:list {locale} (e.g., php artisan route:trans:list en)