Native Locale Names Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require laravel-lang/native-locale-names
   

   Publish the config (if needed):

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

2. First Use Case: Retrieve a native locale name for a given locale code:

   use LaravelLang\NativeLocaleNames\LocaleNames;
   
   $nativeName = LocaleNames::get('en'); // Returns "English"
   $nativeName = LocaleNames::get('fr'); // Returns "Français"
   $nativeName = LocaleNames::get('ja'); // Returns "日本語"
   

3. Where to Look First:

   • Facade: LaravelLang\NativeLocaleNames\Facades\LocaleNames
   • Service Provider: LaravelLang\NativeLocaleNames\NativeLocaleNamesServiceProvider
   • Config File: config/native-locale-names.php (if published)
   • Documentation: Laravel Lang Native Locale Names

Implementation Patterns

Usage Patterns

1. Retrieving Native Locale Names:

   // Basic usage
   $name = LocaleNames::get('es'); // "Español"
   
   // With fallback (returns 'es' if not found)
   $name = LocaleNames::get('es', 'es');
   
   // Get all available locales with native names
   $allLocales = LocaleNames::all();
   

2. Integration with Laravel Localization:

   // In a controller or service
   $currentLocale = app()->getLocale();
   $nativeName = LocaleNames::get($currentLocale);
   
   // In Blade templates
   @php
   $locale = 'pt-BR';
   $nativeName = LaravelLang\NativeLocaleNames\Facades\LocaleNames::get($locale);
   @endphp
   
   <select name="locale">
       <option value="en">{{ LaravelLang\NativeLocaleNames\Facades\LocaleNames::get('en') }}</option>
       <option value="pt-BR">{{ $nativeName }}</option>
   </select>
   

3. Dynamic Language Switcher:

   // In a language switcher component
   $locales = [
       'en' => 'English',
       'fr' => 'Français',
       'de' => 'Deutsch',
       'ja' => '日本語',
   ];
   
   // Replace hardcoded values with native names
   $locales = collect($locales)->mapWithKeys(function ($value, $key) {
       return [ $key => LocaleNames::get($key) ];
   });
   

4. Form Labels and Placeholders:

   // In a Form Request or Form class
   public function rules()
   {
       return [
           'language' => 'required|in:'.implode(',', array_keys(LocaleNames::all())),
       ];
   }
   
   public function messages()
   {
       return [
           'language.in' => 'Please select a valid language.',
       ];
   }
   

5. API Responses:

   // Return native locale names in API responses
   return response()->json([
       'supported_locales' => collect(LocaleNames::all())->mapWithKeys(fn($name, $code) => [$code => $name]),
   ]);
   

Workflows

1. Locale Selection Dropdown:

   • Use LocaleNames::all() to populate a dropdown in settings or profile pages.
   • Example:

     $locales = LocaleNames::all();
     return view('settings.locale', compact('locales'));
     

     <select name="locale">
         @foreach($locales as $code => $name)
             <option value="{{ $code }}">{{ $name }}</option>
         @endforeach
     </select>
     

2. User Profile Localization:

   • Store the locale code (e.g., en, fr-CA) in the database and display the native name:

     $userLocale = $user->locale;
     $nativeLocaleName = LocaleNames::get($userLocale);
     

     <p>Your preferred language: {{ $nativeLocaleName }}</p>
     

3. Admin Panel Filters:

   • Use native names for region/language filters in admin dashboards:

     $regions = [
         'US' => LocaleNames::get('en-US'),
         'FR' => LocaleNames::get('fr-FR'),
         'JP' => LocaleNames::get('ja-JP'),
     ];
     

4. Multilingual SEO:

   • Generate locale-specific metadata using native names:

     $locale = 'es-ES';
     $nativeName = LocaleNames::get($locale);
     return response()->json([
         'title' => "Página en $nativeName",
     ]);
     

Integration Tips

1. Cache Native Names:

   • Cache frequently accessed locale names to reduce overhead:

     $nativeName = Cache::remember("locale_name_{$locale}", now()->addHours(1), function() use ($locale) {
         return LocaleNames::get($locale);
     });
     

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

   • Use both packages together for a complete locale management system:

     use LaravelLang\LocaleList\Facades\LocaleList;
     use LaravelLang\NativeLocaleNames\Facades\LocaleNames;
     
     $allLocales = LocaleList::getNames(); // Get all locale codes
     $nativeNames = collect($allLocales)->mapWithKeys(function ($code) {
         return [$code => LocaleNames::get($code)];
     });
     

3. Extend with Custom Locales:

   • Add custom locale names by extending the service:

     // In a service provider
     $this->app->extend('locale-names', function ($service) {
         $service->add('custom-code', 'Custom Locale Name');
         return $service;
     });
     

4. Localization Middleware:

   • Set the native locale name in the session or view data:

     // In middleware
     $request->merge([
         'native_locale_name' => LocaleNames::get(app()->getLocale()),
     ]);
     

5. Testing:

   • Mock the LocaleNames facade in tests:

     $this->mock(LaravelLang\NativeLocaleNames\Facades\LocaleNames::class)
          ->shouldReceive('get')
          ->with('es')
          ->andReturn('Español');
     

Gotchas and Tips

Pitfalls

1. Missing Locales:

   • Not all locale codes are supported. Check the supported locales list.
   • Fix: Use a fallback value or handle missing locales gracefully:

     $name = LocaleNames::get('xx', 'Unknown'); // Fallback to 'Unknown'
     

2. Case Sensitivity:

   • Locale codes are case-sensitive (e.g., EN vs. en). Always use lowercase.
   • Fix: Normalize locale codes before passing them:

     $locale = strtolower($request->input('locale'));
     $name = LocaleNames::get($locale);
     

3. Regional Variations:

   • Some locales have regional variants (e.g., pt vs. pt-BR). The package may return the base language name.
   • Fix: Use specific locale codes (e.g., pt-BR) for accurate results.

4. Caching Issues:

   • If you update the package or add custom locales, clear the cache:

     php artisan cache:clear
     php artisan view:clear
     

5. Dependency Conflicts:

   • Ensure compatibility with laravel-lang/locale-list (required dependency). Update both packages together:

     composer update laravel-lang/native-locale-names laravel-lang/locale-list
     

6. Performance:

   • Loading all locales (LocaleNames::all()) can be resource-intensive for large applications.
   • Fix: Cache the result or load only the locales you need:

     $requiredLocales = ['en', 'fr', 'de'];
     $nativeNames = collect($requiredLocales)->map(fn($code) => LocaleNames::get($code));
     

Debugging

1. Check Supported Locales:

   • Verify if a locale is supported:

     if (LocaleNames::has('es')) {
         $name = LocaleNames::get('es');
     } else {
         // Handle unsupported locale
     }
     

2. Log Missing Locales:

   • Debug missing locales by logging unsupported codes:

     try {
         $name = LocaleNames::get('unsupported-locale');
     } catch (\InvalidArgumentException $e) {
         \Log::warning("Unsupported locale: unsupported-locale", ['exception' => $e]);
     }
     

3. Validate Locale Codes:

   • Ensure locale codes are valid before passing them to the