Languages Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require rinvex/languages
   

   Publish the config (optional):

   php artisan vendor:publish --provider="Rinvex\Languages\LanguagesServiceProvider"
   

2. First Use Case Retrieve a language by ISO code (e.g., English):

   use Rinvex\Languages\Facades\Languages;
   
   $english = Languages::get('en');
   // Returns array with keys: name, native, iso639_1, iso639_2, iso639_3, etc.
   

3. Where to Look First

   • Facade: Rinvex\Languages\Facades\Languages (primary entry point).
   • Config: config/languages.php (customize default language or data source).
   • Data: vendor/rinvex/languages/src/Data/languages.php (raw language data).

Implementation Patterns

Core Workflows

1. Fetching Language Data

   // By ISO code (e.g., 'es' for Spanish)
   $spanish = Languages::get('es');
   
   // By native name (case-insensitive)
   $french = Languages::getByNative('français');
   
   // All languages as a collection
   $allLanguages = Languages::all();
   

2. Filtering Languages

   // Filter by language family (e.g., 'Indo-European')
   $indoEuropean = Languages::where('family', 'Indo-European')->get();
   
   // Filter by script (e.g., 'Latin')
   $latinScript = Languages::where('script', 'Latin')->get();
   

3. Integration with Laravel

   • Localization: Use language data to dynamically populate dropdowns:

     $languages = Languages::all()->pluck('name', 'iso639_1');
     return view('lang-selector', compact('languages'));
     

   • Middleware: Detect user language and set locale:

     public function handle($request, Closure $next) {
         $userLang = Languages::get($request->header('Accept-Language'));
         app()->setLocale($userLang['iso639_1']);
         return $next($request);
     }
     

4. Caching Enable caching in config/languages.php:

   'cache' => true, // Caches all() and get() calls
   'cache_ttl' => 60, // Cache TTL in minutes
   

Gotchas and Tips

Pitfalls

1. Case Sensitivity

   • getByNative() is case-insensitive, but get() (ISO code) is case-sensitive. Use 'en' instead of 'EN'.

2. Data Overrides

   • Customizing language data requires modifying the published config or extending the package (see below). Avoid direct vendor file edits.

3. Performance

   • Disable caching ('cache' => false) if language data changes frequently (e.g., in a multitenant app with custom languages).

4. Missing Data

   • Some languages may lack certain attributes (e.g., language_culture). Handle with:

     $language = Languages::get('ln') ?? [];
     $culture = $language['language_culture'] ?? 'default';
     

Debugging

• Validate ISO Codes: Use Languages::isValidIsoCode('xx') to check if a code exists.
• Log Missing Data: Add a fallback for undefined keys:

  $language = Languages::get('xx') + ['fallback' => 'N/A'];
  

Extension Points

1. Custom Data Source Override the default data in config/languages.php:

   'data' => [
       'custom' => [
           'iso639_1' => 'xx',
           'name' => 'Custom Language',
           'native' => 'Custom Native',
           // ... other attributes
       ],
   ],
   

2. Adding New Attributes Extend the Language model (if needed) by publishing the package and modifying:

   // app/Languages/Extensions/LanguageExtension.php
   namespace App\Languages\Extensions;
   
   use Rinvex\Languages\Models\Language;
   
   class LanguageExtension extends Language {
       public function getCustomAttribute() {
           return $this->attributes['custom_key'] ?? null;
       }
   }
   

   Bind the extension in AppServiceProvider:

   Languages::extend(function ($app) {
       return new \App\Languages\Extensions\LanguageExtension();
   });
   

3. Localization Hooks Trigger events when language data is loaded:

   Languages::macro('afterGet', function ($callback) {
       $this->afterGetCallbacks[] = $callback;
   });
   
   // Usage:
   Languages::get('en')->afterGet(function ($language) {
       // Modify or log language data
   });
   

Pro Tips

• Batch Processing: Use Languages::all() to preload data for bulk operations (e.g., seeding a database).
• API Integration: Expose language endpoints:

  Route::get('/languages/{iso}', function ($iso) {
      return Languages::get($iso);
  });
  

• Testing: Mock the facade for unit tests:

  $this->mock(Languages::class)->shouldReceive('get')->andReturn(['name' => 'Test']);