Language Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer (though note the read-only warning):

   composer require beloop/language-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Beloop\LanguageBundle\BeloopLanguageBundle::class => ['all' => true],
   ];
   

2. First Use Case Translate a string in a controller or template:

   use Beloop\LanguageBundle\Translator\Translator;
   
   class MyController extends AbstractController {
       public function index(Translator $translator) {
           $translated = $translator->trans('Hello world');
           return new Response($translated);
       }
   }
   

   Or in Twig:

   {{ 'Hello world'|trans }}
   

3. Where to Look First

   • Configuration: Check config/packages/beloop_language.yaml (if auto-generated).
   • Services: Review BeloopLanguageBundle::getServices() in the bundle class.
   • Translations: Default paths are translations/messages.{locale}.yml (Symfony standard).

Implementation Patterns

Core Workflows

1. Translation Management

   • Adding Translations: Create YAML files in translations/messages.{locale}.yml:

     # translations/messages.en.yml
     hello: "Hello, %name%!"
     

     Use placeholders with %var% syntax.
   • Dynamic Context: Pass context arrays to override translations:

     $translator->trans('hello', ['%name%' => 'John']);
     

2. Integration with Symfony Components

   • Dependency Injection: The bundle extends Symfony’s TranslatorInterface, so use it like any Symfony translator.
   • Event Listeners: Extend functionality via kernel.request events to modify translations dynamically.

3. Custom Domains

   • Define domain-specific translations (e.g., validation.yml) by extending the bundle’s configuration:

     # config/packages/beloop_language.yaml
     beloop_language:
         domains: ['messages', 'validation']
     

Advanced Patterns

• Fallback Chains: Configure fallback locales in config/packages/beloop_language.yaml:

  beloop_language:
      fallback_locales: ['en', 'fr']
  

• Runtime Locale Switching: Use the LocaleListener (if included) to switch locales via URL parameters:

  // In a controller
  $request->setLocale('fr');
  

Gotchas and Tips

Pitfalls

1. Archived Status:

   • The package is read-only (no PRs accepted). Use at your own risk or fork for modifications.
   • Check the main Beloop Components repo for updates.

2. Outdated Dependencies:

   • Last release in 2019 may conflict with newer Symfony/Laravel versions.
   • Test thoroughly with your stack (e.g., Symfony 5.x+ may need polyfills).

3. Missing Documentation:

   • No detailed docs beyond the README. Reverse-engineer usage from:
     • src/Resources/config/services.yaml (service definitions).
     • src/DependencyInjection/ (compiler passes, extensions).

Debugging Tips

• Translation Not Found: Verify the locale file exists in translations/messages.{locale}.yml and the domain is registered.

  php bin/console debug:translation --all
  

• Locale Switching Issues: Ensure the LocaleListener is enabled (if used) and the locale route parameter is configured in your router.

Extension Points

1. Custom Translator: Override the translator service in config/services.yaml:

   services:
       Beloop\LanguageBundle\Translator\Translator:
           arguments:
               $loader: '@your_custom_loader'
   

2. Add New Translation Sources: Extend the bundle’s Loader class to support JSON/XML translations:

   class CustomLoader extends \Beloop\LanguageBundle\Loader\YamlFileLoader {
       public function load($resource, $locale, $domain = 'messages') {
           // Custom logic
       }
   }
   

3. Event Subscribers: Listen to BeloopLanguageBundleEvents::TRANSLATION_MODIFIED (if exposed) to intercept translations.

Configuration Quirks

• Default Locale: Set in config/packages/beloop_language.yaml or fall back to Symfony’s default:

  beloop_language:
      default_locale: 'en'
  

• Caching: Translations are cached by default. Clear cache after adding new translations:

  php bin/console cache:clear