Native Currency Names Laravel Package

Getting Started

Install via Composer:

composer require laravel-lang/native-currency-names

Publish translations (stores files in resources/lang/vendor/native-currency-names):

php artisan lang:publish --provider="LaravelLang\NativeCurrencyNames\ServiceProvider"

First use case: Replace hardcoded currency symbols/names in checkout flows:

// Before
echo 'Price: $' . $amount;

// After
echo 'Price: ' . __('native-currency-names::currency.USD') . ' ' . $amount;

Key files to inspect:

• config/native-currency-names.php (default: empty, but extensible)
• resources/lang/vendor/native-currency-names/ (all locale files)

Implementation Patterns

Core Workflow

1. Translation Access:

   // Get currency name for locale (e.g., 'ja' for Japanese)
   $currencyName = __('native-currency-names::currency.USD', [], 'ja'); // "ドル"
   
   // Fallback to default locale if missing
   $currencyName = __('native-currency-names::currency.EUR');
   

2. Dynamic Locale Handling:

   // In a multi-locale app, use the current app locale
   $currency = __('native-currency-names::currency.' . $currencyCode);
   
   // Or pass explicit locale
   $currency = trans('native-currency-names::currency.USD', [], 'ar'); // "دولار"
   

3. Integration with Payment Gateways:

   // Example: Localized payment confirmation
   $payment = Payment::find($id);
   $locale = $payment->user->locale;
   $currencyName = __('native-currency-names::currency.' . $payment->currency);
   
   return "Your payment of {$payment->amount} {$currencyName} was successful.";
   

Advanced Patterns

1. Blade Directives:

   // Create a custom Blade directive for reusable currency display
   Blade::directive('currency', function ($code) {
       return "<?php echo __('native-currency-names::currency.{$code}'); ?>";
   });
   
   // Usage in Blade:
   @currency('USD') // Outputs "Dollar" or localized equivalent
   

2. Model Scopes:

   // Add a localized currency name to Eloquent models
   public function getLocalizedCurrencyNameAttribute()
   {
       return __('native-currency-names::currency.' . $this->currency);
   }
   

3. API Responses:

   // Localize currency names in API responses
   return response()->json([
       'amount' => $order->amount,
       'currency_name' => __('native-currency-names::currency.' . $order->currency),
       'locale' => $request->header('Accept-Language')
   ]);
   

4. Form Labels:

   // Localized currency input labels
   <label for="amount">
       {{ __('Amount in') }} @currency('USD')
   </label>
   

Testing Patterns

1. Unit Tests:

   public function testCurrencyTranslation()
   {
       $this->assertEquals('ドル', __('native-currency-names::currency.USD', [], 'ja'));
       $this->assertEquals('Euro', __('native-currency-names::currency.EUR', [], 'en'));
   }
   

2. Feature Tests:

   public function testCheckoutCurrencyDisplay()
   {
       $response = $this->actingAs($user)->get('/checkout');
       $response->assertSee('100ドル'); // Japanese locale
   }
   

3. Locale-Specific Tests:

   public function testAllLocales()
   {
       $locales = ['ja', 'de', 'ar', 'hi']; // Test critical locales
       foreach ($locales as $locale) {
           $this->assertNotNull(__('native-currency-names::currency.USD', [], $locale));
       }
   }
   

Gotchas and Tips

Common Pitfalls

1. Locale Fallback:

   • If a locale isn’t supported, the package returns the key (e.g., currency.USD). Always provide a fallback:

     __('native-currency-names::currency.USD', [], 'xx', 'en'); // Fallback to English
     

2. Currency Code Mismatch:

   • The package uses ISO 4217 codes (e.g., USD, not US). Verify your data matches:

     // Wrong: 'US' → returns 'currency.US' (not found)
     // Right: 'USD' → returns correct translation
     

3. Caching:

   • Translations are cached like all Laravel translations. Clear cache after updates:

     php artisan view:clear
     php artisan cache:clear
     

4. Blade Cache:

   • If using @currency directives, clear Blade cache:

     php artisan view:clear
     

Debugging Tips

1. Check Available Locales:

   // List all available locales
   $locales = array_keys(LaravelLang\NativeCurrencyNames\NativeCurrencyNames::getLocales());
   

2. Verify Currency Codes:

   // Check if a currency code exists for a locale
   $exists = file_exists(resource_path("lang/vendor/native-currency-names/{$locale}.php"))
           && str_contains(file_get_contents(resource_path("lang/vendor/native-currency-names/{$locale}.php")), "currency.{$code}");
   

3. Fallback Logic:

   • Use trans() with fallback for graceful degradation:

     $name = trans('native-currency-names::currency.USD', [], 'ja', 'en');
     // Falls back to English if 'ja' locale is missing the key
     

Extension Points

1. Custom Locales:

   • Add new locales by extending the package’s NativeCurrencyNames class or publishing custom translations:

     php artisan lang:publish --provider="LaravelLang\NativeCurrencyNames\ServiceProvider" --tag=custom
     

2. Override Translations:

   • Override specific translations in your resources/lang/vendor/native-currency-names/ directory. Files in this directory take precedence.

3. Programmatic Access:

   • Access raw data without translation:

     $data = LaravelLang\NativeCurrencyNames\NativeCurrencyNames::getData();
     $currencyName = $data['ja']['currency']['USD']; // "ドル"
     

4. Dynamic Currency Codes:

   • For dynamic currencies (e.g., crypto), extend the package or use a hybrid approach:

     $currencyName = $this->getCurrencyName($code, $locale);
     // Custom logic for unsupported codes
     

Performance Considerations

1. Avoid Runtime Lookups:

   • Cache frequently accessed currency names:

     $cacheKey = "currency_{$code}_{$locale}";
     $name = cache()->remember($cacheKey, now()->addHours(1), function() use ($code, $locale) {
         return __('native-currency-names::currency.' . $code, [], $locale);
     });
     

2. Locale Negotiation:

   • Optimize locale detection to avoid redundant calls:

     $locale = app()->getLocale(); // Use app's current locale
     $currencyName = __('native-currency-names::currency.' . $code, [], $locale);
     

Configuration Quirks

1. Default Config:

   • The package ships with minimal config (config/native-currency-names.php). Extend it for custom behavior:

     'default_locale' => 'en',
     'fallback_locale' => 'en',
     'supported_currencies' => ['USD', 'EUR', 'JPY'], // Optional: whitelist
     

2. Service Provider:

   • The package registers its own service provider. If you need to override it, bind your own:

     $this->app->bind(
         'LaravelLang\NativeCurrencyNames\NativeCurrencyNames',
         function ($app) {
             return new YourCustomCurrencyNames();
         }
     );
     

Localization-Specific Tips

1. Right-to-Left (RTL) Languages:

   • Ensure your UI accounts for RTL direction (e.g., Arabic, Hebrew):

     <div dir="rtl">
         {{ __('native-currency-names::currency.SAR') }} {{ $amount }}
     </div>
     

2. Currency Symbols:

   • Combine with Laravel’s number_format() for locale-aware formatting:

     $formatted = number_format($amount, 2, app()->getLocale() === 'ja' ? ',' : '.', ' ');
     echo "{$formatted} " . __('native-currency-names::currency.JPY');
     

3. Pluralization:

   • Pair with Laravel’s pluralization for amounts:

     $rules = __('You have :count item|You have :count items', ['count' => $