Locale List Laravel Package

Getting Started

1. Install the package via Composer:

   composer require laravel-lang/locale-list
   

2. No configuration required – the package ships with a static locale catalog (LocaleList::all()) and helper methods.
3. First use case: Validate user-submitted locale codes in a request:

   use LaravelLang\LocaleList\LocaleList;
   
   $request->validate([
       'locale' => ['required', 'string', 'in:' . implode(',', LocaleList::codes())],
   ]);
   

4. Check available helpers in the LocaleList facade (or LocaleList class, as it’s not strictly facade-bound) – start with LocaleList::all(), LocaleList::codes(), LocaleList::names(), LocaleList::findByCode().

Implementation Patterns

• Language switcher dropdowns
  Use LocaleList::names() to populate a <select>:

  $locales = LocaleList::names(); // ['en' => 'English', 'fr' => 'Français', ...]
  // In Blade: @foreach($locales as $code => $name)
  

• User preference storage
  Validate and store preferred locale against the curated list:

  $validatedLocale = LocaleList::findByCode($input['locale']) 
      ? $input['locale'] 
      : app()->getLocale(); // fallback
  

• API payload validation
  Ensure incoming locale params match your supported locales:

  Rule::in(LocaleList::codes()), // or `Rule::in(LocaleList::codes('iso-639-1'))`
  

• Configuration defaults
  Use LocaleList::codes() as defaults in config or seeders:

  // config/app.php
  'supported_locales' => LocaleList::codes(['en', 'es', 'pt-BR']),
  

• Form request rules
  Extend FormRequest with reusable locale validation:

  protected function getValidatorInstance()
  {
      $validator = parent::getValidatorInstance();
      $validator->addRule('locale', 'in:'.implode(',', LocaleList::codes()));
      return $validator;
  }
  

Gotchas and Tips

• Locale codes may include regions – e.g., pt-BR, zh-Hans. Use LocaleList::codes() (default) rather than ISO-639-1 only codes (LocaleList::codes('iso-639-1')) unless your app strictly supports language-only codes.

• Case sensitivity matters – always compare locale strings exactly as returned by LocaleList::codes() (typically lowercase + hyphen, per BCP 47). Don’t assume en-US == en_us.

• No filtering by locale status – this package does not distinguish between supported, active, or complete locales. It’s a reference list, not a runtime registry. Combine with your own config or database for activation logic.

• Custom extensions – if your app uses non-standard locales (e.g., zh-Hant-TW), validate them manually:

  in_array($code, LocaleList::codes()) || in_array($code, config('app.custom_locales', []))
  

• Caching note – since the list is static, there’s no caching layer provided, but you can safely cache calls to it (e.g., via Cache::remember()), especially if building large locale arrays in Blade or API endpoints.

• Translation name consistency – LocaleList::names() returns English names only. For localized display names, integrate with symfony/translation or laravel-lang/lang for full translations.