Laravel Locales Laravel Package

Getting Started

1. Install the package via Composer: composer require chinleung/laravel-locales
2. Publish config: php artisan vendor:publish --provider="ChinLeung\Locales\LocalesServiceProvider" — generates config/locales.php
3. Configure supported locales in config/locales.php, e.g.:

   'locales' => [
       'en' => ['name' => 'English', 'script' => 'Latn', 'native' => 'English'],
       'fr' => ['name' => 'French', 'script' => 'Latn', 'native' => 'Français'],
   ],
   

4. Use the middleware: In app/Http/Kernel.php, add 'locale' => \ChinLeung\Locales\Middleware\SetLocale::class to $routeMiddleware
5. First use case: Wrap localized routes with the locale middleware and use route('home') — the package automatically prepends the current locale (if prefix mode is enabled).

Implementation Patterns

• Route grouping with locale prefix: Use ->middleware('locale') on grouped routes; the package detects locale from URL segment (/fr/home → fr) or session/app locale.
• Localized URL generation: Use the locale_url() helper in views:

  <a href="{{ locale_url('home') }}">Home</a>
  <a href="{{ route('home', [], locale: 'fr') }}">Français</a>
  

• Switching locale in UI: Provide a simple language switcher:

  @foreach(config('locales.locales') as $code => $meta)
      <a href="{{ locale_url('', $code) }}">{{ $meta['native'] }}</a>
  @endforeach
  

• Controller-level locale awareness: Inject \ChinLeung\Locales\Facades\Locales to get current locale, list supported locales, or detect fallback:

  use ChinLeung\Locales\Facades\Locales;
  
  $current = Locales::current();      // e.g. 'en'
  $all = Locales::all();              // ['en', 'fr']
  $fallback = Locales::fallback();    // 'en' (default fallback)
  

• Translation sync: The package respects Laravel’s locale and fallback_locale; __() and trans() continue to work as expected, but now locale switching is centralized.

Gotchas and Tips

• URL prefix vs. no-prefix mode: By default, prefix is enabled in config/locales.php. Disable via 'prefix' => false if you want cookie/session-based locale only (e.g., for dashboards). Warning: Changing this mid-project requires URL/redirect handling.
• Missing locale fallback: If a user hits /de/unknown but de isn’t in config/locales.locales, the package silently falls back to default locale — ensure your middleware stack doesn’t rely on exceptions here.
• Debugging locale detection: Use Locales::detectFromRequest() to trace how locale is inferred (path → session → cookie → header → default).
• Caching routes: If using route() caching (e.g., php artisan route:cache), locale-prefixed routes won’t auto-render with locale unless you use the helper locale_url() instead of route() for dynamic links.
• Extensibility: Override LocaleDetector via config/locales.php (see detector key) to add custom logic (e.g., subdomain-based: fr.example.com).
• SEO note: Always include <link rel="alternate" hreflang="..."> via blade partials using locale_url($path, $locale) to generate canonical hrefs.