Locale Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require goc/locale-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       GardenOfConcepts\LocaleBundle\GardenOfConceptsLocaleBundle::class => ['all' => true],
   ];
   

2. Configuration: Define locales in config/packages/goc_locale.yaml:

   goc_locale:
       default_locale: 'en'
       locales: ['en', 'de', 'fr']
   

3. First Use Case: Localize a number in Twig:

   {{ 1234.56|goc_number(locale='de') }}  {# Outputs: 1.234,56 #}
   

Key Files to Review

• Resources/doc/twig.rst: Twig filter documentation.
• DependencyInjection/GardenOfConceptsLocaleExtension.php: Bundle configuration.
• Twig/GardenOfConceptsLocaleExtension.php: Core Twig filters.

Implementation Patterns

Common Workflows

1. Locale-Aware Number Formatting:

   {{ 1000|goc_number(locale='fr') }}  {# 1 000 #}
   {{ 0.5|goc_percent(locale='de') }} {# 50 % #}
   

2. Dynamic Locale Switching: Use a user locale from session:

   {% set userLocale = app.session.get('user_locale', 'en') %}
   {{ 123.45|goc_currency(locale=userLocale, currency='EUR') }}
   

3. Date/Time Localization:

   {{ '2023-12-25'|date('Y-m-d')|goc_date(locale='ja') }} {# 2023年12月25日 #}
   

4. Country Code Conversion:

   {{ 'US'|goc_country_name(locale='de') }} {# Vereinigte Staaten #}
   

Integration Tips

• Symfony Forms: Use goc_number/goc_currency in form themes for localized labels.
• API Responses: Apply filters in serializers (e.g., JsonResponse):

  return new JsonResponse([
      'price' => $product->price->format('de')
  ]);
  

• Fallback Locales: Configure a fallback in goc_locale.yaml:

  locales: ['en', 'de']
  fallback_locale: 'en'
  

Gotchas and Tips

Pitfalls

1. Missing intl Extension:

   • Error: Class 'IntlDateFormatter' not found.
   • Fix: Enable PHP’s intl extension (sudo apt-get install php-intl on Ubuntu).

2. Unsupported Locales:

   • Issue: Filters like goc_currency fail for unsupported locales (e.g., ar).
   • Workaround: Stick to ICU-supported locales.

3. Twig Cache Invalidation:

   • Problem: Changes to Twig filters require cache clearing:

     php bin/console cache:clear
     

4. Currency Symbols:

   • Quirk: goc_currency uses locale-specific symbols (e.g., € for de). Override via currency parameter:

     {{ 100|goc_currency(locale='en', currency='USD') }} {# $100 #}
     

Debugging

• Check Available Locales:

  use IntlDateFormatter;
  var_dump(IntlDateFormatter::getAvailableLocales());
  

• Validate Locale Syntax: Use full locale tags (e.g., en_US instead of en). Test with:

  {{ 'en_US'|goc_country_name }}
  

Extension Points

1. Custom Formatters: Extend GardenOfConcepts\LocaleBundle\Twig\GardenOfConceptsLocaleExtension to add new filters.

2. Override Defaults: Configure locale-specific rules in config/packages/goc_locale.yaml:

   goc_locale:
       number_formatter:
           decimal_separator: ','
           grouping_separator: '.'
   

3. Address/Salutation (Future): Monitor the repo for updates or fork to implement missing features (e.g., address formatting).

Pro Tips

• Performance: Cache formatted values if reused (e.g., in loops):

  {% set cachedPrice = 100|goc_currency(locale=userLocale) %}
  

• Testing: Use IntlDateFormatter directly in PHPUnit for deterministic tests:

  $formatter = new IntlDateFormatter('de_DE', IntlDateFormatter::NONE, IntlDateFormatter::NONE, 'dd.MM.yyyy', IntlDateFormatter::GREGORIAN);