Native Locale Names Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require laravel-lang/native-locale-names
   

   Ensure your Laravel version (11+) is supported (check releases).

2. First Use Case: Display a locale name in its native script (e.g., "हिन्दी" for Hindi):

   use LaravelLang\NativeLocaleNames\LocaleNames;
   
   $localeName = LocaleNames::get('hi_IN'); // Returns 'हिन्दी'
   echo $localeName;
   

3. Where to Look First:

   • Documentation for API reference.
   • Supported Locales to verify coverage.
   • LocaleNames::get($locale) for direct lookups, or LocaleNames::all() for a full list.

Implementation Patterns

Core Workflows

1. Dynamic Locale Display in Views:

   // Blade template
   <select name="locale">
       @foreach (LocaleNames::all() as $locale => $name)
           <option value="{{ $locale }}">{{ $name }}</option>
       @endforeach
   </select>
   

   Use case: Language switcher dropdowns, user profile settings.

2. Integration with Laravel’s Localization:

   $currentLocale = app()->getLocale();
   $nativeName = LocaleNames::get($currentLocale);
   // Example: Display "Welcome, User! (你好, 用户!)" in Chinese.
   

3. API Responses:

   return response()->json([
       'locales' => LocaleNames::all(),
   ]);
   

   Use case: Frontend state management (e.g., React/Vue apps).

4. Fallback Handling:

   $name = LocaleNames::get('xx_XX', 'Unknown Locale'); // Fallback if unsupported
   

Advanced Patterns

1. Caching for Performance:

   $names = Cache::remember('locale-names', now()->addYear(), function () {
       return LocaleNames::all();
   });
   

   Tip: Cache the full list if your app has static locale requirements (e.g., admin panels).

2. Combining with laravel-lang/locale-list:

   use LaravelLang\LocaleList\LocaleList;
   
   $locales = LocaleList::getSupportedLocales();
   $nativeNames = collect($locales)->mapWithKeys(fn ($locale) => [
       $locale => LocaleNames::get($locale)
   ]);
   

   Use case: Filter or sort locales dynamically.

3. Service Provider Binding (for dependency injection):

   // app/Providers/AppServiceProvider.php
   public function register()
   {
       $this->app->singleton('locale.names', function () {
           return new LocaleNames();
       });
   }
   

   Use case: Centralize locale logic in a single service.

4. Testing:

   public function test_locale_names()
   {
       $this->assertEquals('English', LocaleNames::get('en_US'));
       $this->assertEquals('Español', LocaleNames::get('es_ES'));
   }
   

Gotchas and Tips

Pitfalls

1. Unsupported Locales:

   • The package relies on laravel-lang/locale-list. If a locale isn’t listed there, it won’t work here.
   • Fix: Check supported locales or request additions via the issue tracker.

2. Script/Encoding Issues:

   • Some locales (e.g., Arabic, Chinese) use non-Latin scripts. Ensure your database, views, and responses use UTF-8.
   • Fix: Add this to your app/Http/Middleware/EncodeResponseMiddleware:

     public function handle($request, Closure $next)
     {
         $response = $next($request);
         $response->header('Content-Type', 'text/html; charset=UTF-8');
         return $response;
     }
     

3. Caching Quirks:

   • If you update the package, clear cached locale names:

     php artisan cache:clear
     

   • Tip: Use Cache::forget('locale-names') in a command if manual updates are frequent.

4. Namespace Changes:

   • Pre-v2.0 used LaravelLang\NativeLocaleNames\Native. Post-v2.0, it’s LaravelLang\NativeLocaleNames\LocaleNames.
   • Fix: Update imports if migrating from older versions.

5. Sorting Behavior:

   • Sorting is disabled by default (since v2.1.0) to preserve locale-specific ordering.
   • Tip: Sort manually if needed:

     $sortedNames = LocaleNames::all()->sortBy(fn ($name, $locale) => $name);
     

Debugging Tips

1. Verify Locale Format:

   • The package expects locales in xx_XX format (e.g., en_US, hi_IN). Pass en or US for fallbacks.
   • Debug: Use LocaleNames::get('en_US', 'Fallback') to test.

2. Check for Updates:

   • Run composer update laravel-lang/native-locale-names to pull new locales (e.g., ht_HT for Haitian Creole).

3. Log Missing Locales:

   if (!LocaleNames::has('xx_XX')) {
       Log::warning("Unsupported locale: xx_XX");
   }
   

Extension Points

1. Custom Locale Names: Override defaults via a service provider:

   public function boot()
   {
       LocaleNames::extend('en_US', 'Custom English Name');
   }
   

2. Add New Locales:

   • Fork the locale-list repo and submit a PR.
   • Or extend the package:

     LocaleNames::add('xx_XX', 'Native Name');
     

3. Integration with Laravel Translations: Publish and extend translations:

   php artisan vendor:publish --provider="LaravelLang\NativeLocaleNames\NativeLocaleNamesServiceProvider"
   

   Modify resources/lang/vendor/native-locale-names/xx_XX.php for customizations.

4. Performance Optimization:

   • For large apps, preload locales in a bootstrapped service:

     app()->booted(function () {
         $this->app['locale.names']->loadAll();
     });