Native Currency Names Laravel Package

Getting Started

Install via Composer:

composer require laravel-lang/native-currency-names

Publish translations to customize or extend:

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

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

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

// After (Blade)
{{ __('native-currency-names::currency.USD') }} {{ $amount }}

// Or in PHP
echo __('native-currency-names::currency.USD', [], 'ja') . ' ' . $amount; // Outputs: "ドル 100"

Key files to inspect:

• config/native-currency-names.php (minimal default config)
• resources/lang/vendor/native-currency-names/ (all locale files)
• vendor/laravel-lang/native-currency-names/src/NativeCurrencyNames.php (core logic)

Implementation Patterns

Core Translation Workflows

1. Basic Usage:

   // Get currency name for current app locale
   $currency = __('native-currency-names::currency.USD');
   
   // Explicit locale
   $currency = __('native-currency-names::currency.EUR', [], 'de'); // "Euro"
   
   // With fallback
   $currency = __('native-currency-names::currency.XYZ', [], 'en', 'en'); // Returns "XYZ" if missing
   

2. Dynamic Currency Display:

   // In a model or service
   public function getLocalizedCurrencyName(string $code, string $locale = null): string
   {
       return __('native-currency-names::currency.' . $code, [], $locale ?? app()->getLocale());
   }
   

3. Blade Integration:

   // Create a reusable Blade component
   @component('currency', ['code' => 'USD', 'amount' => 100])
       {{ $amount }} {{ __('native-currency-names::currency.' . $code) }}
   @endcomponent
   
   // Or use a directive
   Blade::directive('currency', function ($code) {
       return "<?php echo __('native-currency-names::currency.{$code}'); ?>";
   });
   

Advanced Patterns

1. Multi-Currency Support:

   // For payment gateways or multi-currency apps
   public function formatAmount(float $amount, string $currencyCode, string $locale = null): string
   {
       $locale = $locale ?? app()->getLocale();
       $currencyName = __('native-currency-names::currency.' . $currencyCode, [], $locale);
   
       return number_format($amount, 2) . ' ' . $currencyName;
   }
   

2. API Response Localization:

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

3. Form Localization:

   // Dynamic form labels
   <label for="amount">
       {{ __('Amount in') }} @currency($order->currency)
   </label>
   
   <input type="text" id="amount" name="amount"
          placeholder="{{ __('Enter amount in') }} @currency($order->currency)">
   

4. Testing Patterns:

   // Unit test for translations
   public function testCurrencyTranslations()
   {
       $this->assertEquals('ドル', __('native-currency-names::currency.USD', [], 'ja'));
       $this->assertEquals('Euro', __('native-currency-names::currency.EUR', [], 'en'));
       $this->assertEquals('リアル', __('native-currency-names::currency.BRL', [], 'ja'));
   }
   
   // Feature test for checkout
   public function testCheckoutCurrencyDisplay()
   {
       $response = $this->actingAs($user)->get('/checkout');
       $response->assertSee('100ドル'); // Japanese locale
   }
   

Integration with Payment Systems

1. Stripe/PayPal Localization:

   // Localize payment descriptions
   $description = __('Payment of') . ' ' .
                  __('native-currency-names::currency.' . $order->currency) . ' ' .
                  number_format($order->amount, 2);
   
   // Pass to Stripe
   Stripe::charges()->create([
       'amount' => $order->amount * 100,
       'currency' => $order->currency,
       'description' => $description,
   ]);
   

2. Invoice Generation:

   // Localized invoice footer
   $invoice->footer = sprintf(
       __('Total: %s %s'),
       number_format($total, 2),
       __('native-currency-names::currency.' . $invoice->currency)
   );
   

Gotchas and Tips

Common Pitfalls

1. Currency Code Mismatch:

   • The package uses ISO 4217 codes (e.g., USD, not US or Dollar).
   • Fix: Always use 3-letter codes (e.g., USD, EUR, JPY).
   • Debug: Check available codes with:

     dd(array_keys(LaravelLang\NativeCurrencyNames\NativeCurrencyNames::getData()['en']['currency'] ?? []));
     

2. Missing Locale Fallback:

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

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

3. Caching Issues:

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

     php artisan view:clear
     php artisan cache:clear
     

4. Blade Cache:

   • If using custom directives (e.g., @currency), clear Blade cache:

     php artisan view:clear
     

Debugging Tips

1. Check Available Locales:

   // List all supported locales
   dd(array_keys(LaravelLang\NativeCurrencyNames\NativeCurrencyNames::getLocales()));
   

2. Verify Currency Existence:

   // Check if a currency exists for a locale
   $data = LaravelLang\NativeCurrencyNames\NativeCurrencyNames::getData();
   $exists = isset($data[$locale]['currency'][$code]);
   

3. Inspect Raw Data:

   // Dump all data for debugging
   dd(LaravelLang\NativeCurrencyNames\NativeCurrencyNames::getData());
   

Extension Points

1. Add Custom Locales:

   • Publish translations and extend:

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

   • Add your locale file to resources/lang/vendor/native-currency-names/.

2. Override Translations:

   • Create a file like resources/lang/vendor/native-currency-names/custom.php:

     return [
         'currency' => [
             'USD' => 'Custom Dollar Name',
             'EUR' => 'Custom Euro Name',
         ],
     ];
     

3. Programmatic Access:

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

4. Dynamic Currency Handling:

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

     public function getCurrencyName(string $code, string $locale = null): string
     {
         $locale = $locale ?? app()->getLocale();
         $name = __('native-currency-names::currency.' . $code, [], $locale);
     
         // Fallback for unsupported codes
         return $name !== "currency.{$code}" ? $name : $code;
     }
     

Performance Optimizations

1. Cache Frequently Used Currencies:

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

2. Avoid Redundant Locale Lookups:

   // Store locale in user session or model
   $locale = $user->locale ?? app()->getLocale();
   $currencyName = __('native-currency-names::currency.' . $code, [], $locale);
   

Configuration Quirks

1. Default Config:
   • The package ships with minimal config. Extend in config/native-currency-names.php:

     return [