Gtranslate Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require addweb/gtranslate-bundle:"*@dev"
   

   Ensure AddWeb\GTranslateBundle\AddWebGTranslateBundle::class is registered in config/bundles.php.

2. Configure via config/packages/gtranslate.yaml

   gtranslate:
       script_src: 'https://cdn.gtranslate.net/widgets/latest/dwf.js'  # Default: dark floating
       auto_wrapper: true
       settings:
           default_language: 'en'
           languages: ['en', 'fr', 'es']
   

3. First Use Case: Render the Widget in Twig

   {{ gtranslate_widget() }}
   

   Outputs the GTranslate widget with default settings.

Implementation Patterns

Core Workflows

1. Global Widget Integration

   • Use gtranslate_widget() in your base template (e.g., base.html.twig) to include the widget site-wide.
   • Leverage auto_wrapper: true to auto-generate a container (e.g., <div class="gtranslate_wrapper">).

2. Dynamic Overrides Override settings per template or partial:

   {{ gtranslate_widget({
       'script_src': 'https://cdn.gtranslate.net/widgets/latest/float.js',
       'languages': ['en', 'de', 'ja'],
       'wrapper_selector': '.custom-translator'
   }) }}
   

3. Service-Based Usage Inject the GTranslateService in controllers/services:

   use AddWeb\GTranslateBundle\Service\GTranslateService;
   
   public function __construct(private GTranslateService $gtranslate) {}
   
   public function renderWidget(): string
   {
       return $this->gtranslate->render([
           'script_src' => 'https://cdn.gtranslate.net/widgets/latest/dropdown.js',
       ]);
   }
   

4. Environment-Specific Configs Use Symfony’s environment variables or parameter bags for multi-environment setups:

   # config/packages/dev/gtranslate.yaml
   gtranslate:
       settings:
           languages: ['en', 'fr']  # Dev-only languages
   

Integration Tips

• Asset Management: Ensure the script_src CDN is whitelisted in your CSP headers if strict policies are enabled.
• Lazy Loading: For performance, defer the script load:

  {{ gtranslate_widget({'defer': true}) }}
  

• Twig Extensions: Extend the bundle’s Twig function for custom logic (see Extension Points).

Gotchas and Tips

Pitfalls

1. Script Conflicts

   • If the widget fails to load, verify the script_src URL is correct and accessible. Test with browser dev tools (Network tab).
   • Fix: Use absolute URLs (e.g., https://cdn.gtranslate.net/...) instead of relative paths.

2. Wrapper Selector Collisions

   • If auto_wrapper: true and your template already has .gtranslate_wrapper, the widget may render incorrectly.
   • Fix: Explicitly set a unique wrapper_selector or disable auto_wrapper.

3. Caching Issues

   • GTranslate’s CDN may cache old scripts. Force a refresh by appending a version query:

     script_src: 'https://cdn.gtranslate.net/widgets/latest/dwf.js?v=2'
     

4. Twig Function Scope

   • The gtranslate_widget() function is not available in PHP code directly. Use the service or pass data via Twig.

Debugging

• Check Rendered HTML: Inspect the page source to confirm the script and wrapper are injected.
• Console Errors: Look for 404 errors on the script_src or missing gtranslate_widget Twig function.
• Symfony Debug Toolbar: Use the "Config" tab to verify gtranslate bundle settings.

Tips

1. Custom Styling Override GTranslate’s CSS by targeting its classes (e.g., .gtranslate-switcher). Example:

   .gtranslate-switcher {
       right: 20px !important;
   }
   

2. Exclude Pages Skip the widget on specific routes by conditionally rendering in Twig:

   {% if app.request.get('_route') != 'admin.dashboard' %}
       {{ gtranslate_widget() }}
   {% endif %}
   

3. Extension Points Extend the Twig function or service:

   // src/Twig/Extension/GTranslateExtension.php
   class GTranslateExtension extends \Twig\Extension\AbstractExtension
   {
       public function getFunctions()
       {
           return [
               new \Twig\TwigFunction('custom_gtranslate', [$this, 'renderCustomWidget']),
           ];
       }
   
       public function renderCustomWidget(array $options): string
       {
           // Custom logic (e.g., add analytics)
           return (new GTranslateService())->render($options);
       }
   }
   

4. Testing Mock the service in PHPUnit:

   $this->gtranslateService->expects($this->once())
       ->method('render')
       ->with(['script_src' => 'test.js']);
   

5. Fallback for No-JS Provide a static fallback for users with JavaScript disabled:

   <noscript>
       <div class="no-js-translator">
           Translation unavailable. Enable JS or use {{ path('app.translate') }}.
       </div>
   </noscript>
   {{ gtranslate_widget() }}